Technical craft
Technical Writing
4 lessons · ~25 min total
01
A design doc exists to get a decision
~6 minWrite from the decision you need rather than from the system you want to describe.
Key takeaways
- A design doc is a request for a specific decision, not a description of a system
- Name the decision, the reviewers, and the deadline in the opening paragraph
- Docs that ask for thoughts collect opinions; docs that ask for a decision get one
02
Put the answer first
~6 minStructure a technical document so a reader can stop at any point and still have the most important thing.
Key takeaways
- Structure a doc by decreasing importance, not by the order you did the work
- A reader who stops after the first paragraph should still have the right conclusion
- Investigation narrative belongs in the appendix as evidence
03
Write the tradeoffs honestly
~7 minMake the alternatives and the costs of your proposal legible, so the decision survives contact with its critics.
Key takeaways
- Name the cost of your own recommendation before a reviewer finds it
- Document rejected options with reasons, so the review stops relitigating them
- A proposal with only benefits transfers all the skepticism to the reader
04
Driving a doc to a decision
~6 minRun the review so the document closes with an owned decision instead of drifting into silence.
Key takeaways
- Give a doc a review window and say what happens when it closes
- Default to yes absent a blocking objection, so silence cannot veto
- Record the status, the date, and who decided, in the doc itself
Try a sample check
A sample from the Technical Writing track. The real checks unlock with an account.
Technical Writing
Your design doc has been open two weeks. Eleven comments, all about naming and diagram style, and nobody has said yes or no. What went wrong?
Start Technical Writing.
Your first lesson takes five minutes, and you can do it right now without an account.