Tips on writing well¶
https://zodvik.com/posts/on-writing-well/
Summary¶
- Writing technical documents forces clarity, similar to how coding clarifies solutions during interviews.
- Writing tips:
- Write for your audience:
- Ask: Who am I writing for? What are the key takeaways?
- Tailor content based on whether it’s for team members, engineers, or executives.
- Write simply:
- Use short sentences (under 30 words) and ordinary words.
- Remove fluff and avoid jargon unless explained.
- Remove weasel words:
- Replace adjectives with data or details.
- Examples: Replace vague statements with specific, measurable facts.
- Apply the “So what?” test:
- Ensure each sentence adds value or explains relevance.
- Quantify the impact in your narrative.
- Add a structure:
- Use frameworks like SCR (Situation, Complication, Resolution) or standard sections like “Asks” and “Appendix.”
- Be persuasive:
- Prefer active voice and present solutions with confidence.
- Avoid ambiguous or tentative language.
- Non-obsolete writing:
- Use absolute time references, avoid temporal terms like “new.”
- Include context about the document’s author and approval timeline.
Page last modified: 2024-10-04 19:34:16