Write better with Why, What and How Framework

Use can use this in the Project Documentation.


Explain the problem and context.

  • Why is this document important
  • Explain the problem
  • Expected benefits of solving it.
  • Why now

This section is the "hook". People who read the why should feel they need more details(rest of the document).


Describe the solution. Expected outcomes and how to measure it.

  • Success conditions/ Functional requirements
  • Constrains/ Non-functional requirements
  • Trade offs to be made


  • Methodology
  • High level design
  • Tech decisions

You can add how you DON'T want to implement too(out of scope things).

One-PagerProblem or opportunity, Hypothesized benefitsSuccess metrics, ConstraintsDeliverables, Define out-of-scope
Design DocWhy the problem is important, Expected ROIBusiness/product requirements, Technical requirements & constraintsMethodology & system design, Diagrams, experiment results, tech choices, integration
After-action ReviewContext of incident, Root cause analysis (5 Whys)Tangible & intangible impact, Estimates (e.g., downtime, $)Follow-up actions & owners
Writing ContentWhy reading the post is important (e.g., anecdotes)The topic being discussed (e.g., documents we write at work)The insight being shared (e.g., Why-What-How, examples)