How to Write Good (Short) Docs
"I would have written a shorter letter, but I did not have the time."
— Mark Twain1
Overview
This post describes how to write a short document for your teammates. The documents under discussion are commonly referred to as "one-pagers", and are distinct from engineering design docs or other more formal engineering docs.
A one pager might be written to:
- surface an org pain point
- propose a project
- lay out a roadmap
- explain the current state of a system or systems
- announce or document a decision
