How to Write Clear Document?

Filed under Software Architecture, Software Engineering on August 18, 2025. Last updated on August 18, 2025.

Introduction

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.

Key Takeaways

Close the What -> Why -> How loop
- What: The problem or goal
- Why: The motivation
- How: The solution
Construct the document in different dimensions
- Audiences: The readers of the document
- C4 model

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.

What is a clear document?

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.

Solution Approach

Practice What -> Why -> How loop.
Use C4 model to visualize the document.
Think about the audiences and the dimensions.
- audiences: peers, managers, self
- ranks * tech-stacks: (junior, senior, manager, etc.) * (front-end, back-end, mobile, etc.)
- technical aspects: (architecture, design, infrastructure, security, etc.)
- ...

conclusion

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.