Struggling to arrange your 50+ wiki pages into a manageable number of sections? The 5W1H — who, what, where, when, why, and how — might be a better way to organize your articles.
Why organize by 5W1H?
Stay focused. On the landing page, ask your reader to form a question before reading on. By clarifying exactly what they want to get out of reading your documentation, they may avoid getting distracted by other articles that are enticing but irrelevant.
Less curse of knowledge. It’s hard to present what you know for someone who doesn’t. This is especially painful if you organized your articles by project codenames. Think about Toyota.com: If I’m not car-savvy, I’d surely be confused by their various offerings, labeled in codenames rather than target markets:
Psychologically easy to navigate. 5W1H makes 6 categories, and 6 is close enough to the “magical number” of 7. According to the Miller’s Law, that’s the maximal number of items the human brain can juggle in the short-term memory. If you provide, say, 12 categories, then your reader will almost certainly forget the first few ones by the time they read all 12 entries in your Table of Contents.
How does 5W1H fit in software documentations?
“Who”: literally or figuratively
“Who”-questions may be used literally or figuratively.
Literal “who”: humans
In the former case, the questions are about actual humans. Questions may include:
- Which team owns this project? With the answer to this question, you can give credits to the developers behind the scene. For example, with a GitHub repo, you can generate a list of all contributors with All Contributors:
- Who are the target audiences? Is your product catering to professional users in a specific industry? Is it meant to be used only by other teams within the same company? Would families with basic knowledge to computers find this software relevant? This is where you assure targeted users that they’ve come to the right place and turn away non-targeted readers.
- Who should I reach out to for a certain inquiry? This is the “contacts” page of your project: For readers who want to report bugs, you may direct them to a bug tracker tool. For journalists with press inquiries, you can leave the email of your public relations representatives.
Figurative “who”: relations between components
With software components personified as individuals, “who”-questions may also inquiry about the relations between them in a system. Some questions in this category are:
- Where does your software sit in the network?
- What other services does your application depend on to complete its job?
- What client software depends on this piece of software?
When answering these questions, I find sequence diagrams helpful. By telling the story of a typical request-response transaction, a sequence diagram can illuminate relations between components without requiring you to write too many words. Here’s a quick diagram that I made with Mermaid with 2 mins:
Mermaid, the diagram tool, has a straightforward syntax:
sequenceDiagram
Mobile app->>+ Server : User click "Search" with<br>input box set to "apple"
Server ->>+ Database : SELECT * FROM Data<br>WHERE keyword LIKE "%apple%"
Database -->>-Server : There's one result<br>called "apple tree".
Server -->>-Mobile app: Render a text box<br>that says "apple tree"“What” v.s. “where”: code v.s. behavior
These two question words often go hand-in-hand.
“Where”: from behavior to code
“Where”-questions seek to map behaviors to places in the codebase/architecture diagram.
- Where is the thing that drives this behavior?
- Which component is involved to render this?
- If I poke here, what code path will be activated?
Think of your documentation in this “where” section as a debugger, pointing a curious observer to the mechanism under the hood.
Side note: One may argue that the metaphoric “who” might be more suitable for who-does-what questions, and “where” is more appropriate for positions in structures. Indeed, I’ve seen both interpretations put in practice. As long as you use these two words consistently, you’re good to go.
“What”: from code to behavior
On the other hand, “what”-questions are often mapping code to behaviors. Typical questions include:
- What does this piece of code do? Of course, whenever you can, document the intention/motivation of each piece of code as close to the code itself as possible. Preferably, write them in docstrings, so that you don’t even have to think about organizing them at all.
- Just as importantly — What could go wrong if I ignore the instructions and invoke this method like this?
- What is a typical response that I can expect from this API endpoint? Note that, if you have an API contract that goes with your service (such as an OpenAPI specification), auto-mocking tools (such as this) may eliminate the need of writing an answer yourself.
In my paradigm here, “where” and “what” approach one subject from opposite directions. Therefore, whenever you finish writing an answer for either of them, it’s a good habit to consider answering the other. This parity can be valuable in unexpected situations.
“When” and “why” are about context
These two question words are another two that go in pair.
“Why”: Why did something happen?
“Why”-questions have a retrospective nature, so I often reserve “When”-questions for prospective inquiries. Either way, the emphasis is on the conditions/situations/context that something has happened/should happen.
Looking back in time, a “why”-question may ask: What are the particularities that led to this design — Was it new leadership, customer request, or regulatory requirement? How pressing was the emergency that justified the usage of such an ad hoc solution? To answer these questions, you may keep referencing past product requirements documents (PRDs), meeting notes, press coverages, etc., or whatever may justify decisions to a future reader.
“When”: When can I start doing something?
The idea is similar with forward-looking questions. In this category, a “when”-question may ask: Now that we have switched this thing on, when should we turn it off? If I open a support ticket now, in how many days should I expect a resolution? We have installed this firewall, but exactly what kind of attacks are we anticipating? Again, provide contexts and descriptions; the exact date and time are, counterintuitively, quite optional.
Although — in the real world — the “when” also cover backward-looking questions, such a “when” can be seldomly be answered satisfactorily without explaining a “why”. Think about the way you’d answer them in history classes. If a student asks when the Renaissance began, you would talk about the increased international interactions, the rediscovery of ancient artifacts, and the new height that arts and technology had reached around that period of time. All these particularities had contributed to the spark that ignited the movement. A simple “14th to 17th century”, though technically correct, won’t mean too much to inquisitive minds.
How: The least surprising category
Anything that can answer a question that starts with “how do I” belong to this category. They include:
- Tutorials, ranging from one-pager “quick starts” to detailed walkthroughs.
- Incident playbooks, from pointers to kill switches to step-by-step debug guides.
- Design guidelines, from style manuals to even lookbooks (which might not answer “how to do something” as much as it would answer “how would it look if I do this”).
There are plenty of resources that help you write good how-to articles. I’ll omit them here.
Summary
This article present a framework of organizing software documentations. The framework consists of 6 buckets that are mapped to the common question words, “5W1H”:
- “Who” deals with relations, either between the software and the humans involved or between components interacting in a system.
- “Where” maps behavior to code, while “what” does the opposite.
- “Why” inquiries the context of why something happened, whereas “when” anticipates the situation where something should happen.
- “How” is all about solutions.
Let me know if you find this categorization scheme helpful. Better yet, share your documentation in public and let us know in the comments!
