Writing Good Documentation

Amazon Writing Culture

Good intentions don’t work, mechanism work, amazon banned a long time ago

• Purpose driven
• Narrative structure
• Feedback Culture

Related: Web Api Design for API documentation, Logical Thinking for clear communication

Document Types

• Narratives
• Business review
• Press Release FAQ / Visuals
• Promotions of employees
• Correction of Errors

Document Format

• 1 pager
  • High level ideas, with clear purpose problem statements and recommendation
• 6 pager
  • More detailed document covering backgrounds analysis and comprehensive action
• Others
  • 2-pager is often used
  • Recent guidelines suggest 4-pager instead 6-pager to save time

Benefit of Written Documents

• Emphasize substance over style
• Put the reader in control
• generate better questions and feedback
• create a timeless reference

Elements of a Good Documents

• Clear goal
  • Each document should have a specific goal that the review will achieve not just info
• logical flow
  • Start with clear purpose
  • state conclusion upfront
  • guide the reader through story
• clarity
  • Documents should be simple, concise and easy to understand even for unfamiliar audiences
• quality
  • Attention to detail, consistent formatting, and accurate data are crucial for building trust

Document Quality

• Concise
  • Aim 30 words or less per sentence for better readability
• Consistency
  • Use consistent formatting and common expressions to create a cohesive document
• Accuracy
  • Proofread carefully to eliminate spelling, grammar and data errors

Data driven writing

• Use data points
• Analyze objectively
• Drive decisions

Nearly All → 86% Significantly → by 30K items much higher → 70bps from 67.1% to 67.8%

Tools

• Deepl
• Grammarly
• ChatGPT
• Google Gemini and assistants

Summary

• Write with purpose
• Structured and organized
• quality build trust
• data driven