MUST and MUST NOT; On Writing Documentation
Revise documentation, many times, and on separate days to catch confusing parts.
Beware of ambiguities, e.g. X may not do Y. Refer to definitions, e.g. RFC 2119 .
Put yourself into different roles, e.g. the person just looking for samples, the person who wants to read up on every nook and crany, the person who has no technical background etc.
- Don’t Repeat Yourself: Describe it in one place, and then refer to it elsewhere.
Caveat. I should ensure that there is some locality in the references. If I’m throwing the reader all over the place with my links, they’ll lose track of what they were investigating in the first place. Furthermore, that shows that my content needs better organization.
Keep things short. The longer a section is, the harder it is to absorb.
Have examples that demonstrate your concepts. Don’t try to pack many concepts into a single example. Have a glossary if there are more than 10 new concepts.
Make it easy for them to navigate to what they need.
Hyperlinks are great when the writing is read digitally. I should take care that the hyperlink degrades gracefully when the user cannot click on it, e.g. my document getting printed. The reader should still be able to locate the resource.
Keep it simple. The Hemingway Editor gives your writing an education grade level. XKCD’s Simplewriter identifies words that are not in the 1,000 most common English words.
David Parnas’s advice for thesis writers: Start your outline with questions. Answer the questions. Change the questions into headings or remove them.
Write bullet points instead of sentences. Rearrange and group bullet points. Convert the bullet points into prose.
I don’t see why I should convert bullet points into prose. Lists are easier to follow than prose. Furthermore, won’t I be forcing transitional words into the prose? IMO, each bullet point maps to a paragraph in prose.
RFCs As a Solution to Endless Discussions
A Request for Comment (RFC) invites feedback and has a specific timeframe. Strikes the balance between act-fast-fail-fast and waiting for consensus.
The NABC (Need, Approach, Benefits and Competition) model has several advantages. Separating the need from the approach is wise because most contention is on the approach chosen. The ‘Competitors’ section encourages the author to consider alternate approaches instead of blind binary thinking. Presenting options with their implications and limitations invites good discourse. When disqualifying an approach, answer the question, “What would need to be true for this to be a good idea?”
NABC is not the only model out there. The Rust RFC Template is organized into summary, motivation, guide-level explanation, reference-level explanation, drawbacks, rationale and alternatives, prior art, unresolved questions, and future possibilities.
References
- Must and Must Not: On Writing Documentation. Kode Vicious. queue.acm.org . news.ycombinator.com . Dec 9, 2019.
- How to Stop Endless Discussions. Candost Dagdeviren. candost.blog . news.ycombinator.com . Dec 31, 2020.
In writing class, I was taught to target a specific reader. The above suggests that I target multiple types of readers with the same piece. I’m hesitant to overrule what I learnt. Or is it more that the same reader will have different objectives in each read? Sometimes I read docs in order to understand the design; other times, I’m in search of a quick example to get the syntax.