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).

Why? What? How?
One-Pager Problem or opportunity, Hypothesized benefits Success metrics, Constraints Deliverables, Define out-of-scope
Design Doc Why the problem is important, Expected ROI Business/product requirements, Technical requirements & constraints Methodology & system design, Diagrams, experiment results, tech choices, integration
After-action Review Context of incident, Root cause analysis (5 Whys) Tangible & intangible impact, Estimates (e.g., downtime, $) Follow-up actions & owners
Writing Content Why 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)