What I like to see in a design doc

[Notgnoshi]

• template
• there is no universally correct approach
• tailor the document to the team, and the environment
• purpose is primarily to facilitate working together, not necessarily work out a perfect design
• better to be short and incomplete than wall-of-text
• "design doc" can mean many different things. Understand the goal of the document, before you try to write it
  • is it to add clarity around a feature the team doesn't understand?
  • is it to address a shortcoming, and propose a solution?
  • is it to hammer out the technical details of an involved design?
  • is it to satisfy your manager?
• you can't move on to design until you understand what's being designed
• what's being designed? the feature? or the implementation of a well-understood feature?
• when there are multiple alternatives, list them! including the "clearly" poor ones
• when there are multiple alternatives, list what you think the design goals are
• what are design goals? I certainly don't mean the goal of the design, I mean the higher level "what are you optimizing for?" Speed? Performance? Maintenance? Proof-of-concept? Groundwork for a future feature? Experiment with new technology? Kill off legacy cruft that's holding us back?