loadingπ=3+7+15+1+292+1+1+1+2+1+3+1+14+…1111111111111
Filed under Software Architecture, Software Engineering on August 18, 2025. Last updated on August 18, 2025.
In this document, I will share my thoughts on how to write a clear document. First, you can focus on the key takeaways, which are the most important points of the document. Then, I will explain a bit more details about the key takeaways.
Close the What -> Why -> How loop
Construct the document in different dimensions
First, start with problems(goals) and audiences: Clearly define what goals are and who want to achieve them. This is the first what(goal) and first dimension(audience).
Second, explain What -> Why -> How. After the definition of the first what, follow with motivation and causal reasoning, finally present the proposed solution and explain how it will be executed. This is the first why(motivation) and first how(solution). In the first how, there must be more details. So you can start the second iteration of what -> why -> how loop. You can keep refine and iterate the document until you are satisfied.
For the dimensions, audiences and C4 model, they should be the default dimensions you need to consider. You can add more dimensions when you need to.
During my daily work, I have seen many documents that are hard to read. Also, there are good examples of clear documents(e.g. Django). I want to compare them and find the differences.
| Aspect | When Done Poorly | When Done Well |
|---|---|---|
| Purpose | No clear purpose; even the author isn’t sure what to convey; stakeholders misaligned. | Stated upfront; everyone understands the document’s meaning and intended outcome. |
| Audience | Unclear who it’s for; readers can’t tell if it’s relevant and may ignore it. | Tailored to different roles (peers, managers, self); readers quickly find what matters to them. |
| Structure | Content dumped linearly without hierarchy; hard to read; no focus. | Organized in layers: Summary → Reasoning → Execution details; readers can “consume by layer.” |
| Logic | Complex reasoning forced into linear text; causal links missing; contradictions possible. | Causal diagrams or reasoning chains show decision flow; logic is consistent and reviewable. |
| Motivation (Why) | Overemphasis on How; lack of Why; execution is detailed but direction is unclear. | Each level answers What → Why → How, ensuring alignment of purpose and method. |
| Focus | Overloaded with details; no priorities; leads to TL;DR. | Controlled information density: key conclusions first, details optional; lowers reading/decision cost. |
I believe unclear documents often reflect unclear thinking. So whenever I come across a vague document, I try to find the root cause and use it as an opportunity to improve my own thinking. I'm also convinced that clear thinking leads to clear documents, clear code, and clear communication.
It’s not just about writing—this kind of structure applies to many areas like coding and project management. Just as Descartes described in Discourse on the Method, we need to continuously practice questioning, breaking things down, analyzing, and verifying. That’s how we refine our ideas over time.