Documentation: Values¶
Values I think are important for producing the best documentation.
My values for technical documentation¶
Respect¶
Summary: Precise, detailed documentation is not burdensome to users in need of information. Treat them with respect, and give them complete, accurate information which reflects the best of your knowledge and experience.
There is a trope in software, that users are clueless. I have sympathy for this perspective. Too often though, documentation authors, in efforts to work around the perceived incompetence of their users, omit important details, deemed to be "too low-level" or "too complicated" for their readers. Authors express a desire to "shield" users from "excessive detail".
Authors are concerned that detailed, precise documentation will bewilder users, because it is verbose. Or that too many examples will bore users if not every example is relevant to them. As a result of being driven by this fear, documentation authors produce works which lack depth. These works are unhelpful for advanced users, and don't provide a path for less-advanced users to advance beyond their current level of understanding.
Don't omit, hide, sanitize, or censor the full, accurate, true information about your products. Entrust your users with the ability to use and configure the product as much as is possible i.e. as much as you can and do.
Clarity over brevity¶
Summary: When you can't come up with a succinct phrasing to capture an idea, don't be afraid to be verbose. Apply rhetorical techniques where they aid clarity and make information explicit. For example, constrasting with a (dis)similar idea, or reiterating the most important ideas.
Related to the problem of not respecting the reader, is the problem of assuming the reader doesn't have time to read a complete sentence. I unfortunately rarely encounter documentation which says things in more than one way, so as to clarify them. Documentation rarely contains rhetorical devices like contrasting or reiterating, because it is assumed to be too verbose, and users will get bored. To me, this is obviously a mistake, because it demonstrates a prioritisation for brevity over clarity. Users in need, are not asking for less documentation. It sounds really obvious when I put it like that. That's because it should be really obvious.
This is not to say that brevity is not important. It is very important. To supply the right amount of information, in the right place, at the right time. Brevity is important. But clarity is more important. If you ever have to choose between your your documentation being brief and being clear, always choose to be clear.
No dead ends¶
Summary: Include links in your documentation, which connect related aspects of the subject matter in order to provide readers with a more holistic understanding.
Sometimes a page will touch on an important subject, that you have been searching for information about. It will contain only a thin veneer of information. There will be no links to other, tangentially related sections, so as to avoid presenting a holistic, coherent picture of your produce or service. Do not do this.
Use links, liberally, in order to connect concepts. This makes it easier for your reader to form a mental model of the subject, and ultimately better understand the content.
Education¶
Summary: The best documentation not only conveys new information, but it also enhances the reader's understanding of topics that they have already grasped. Don't be afraid to use verbose, precise language to provide readers with different perspectives on systems or tools with which they may already be familiar.
It's a delightful experience to learn something new and exciting when you didn't expect to, or as a side effect of learning something else. To foster these experiences, provide tangential educational material inline in your documentation, to allow users to learn more about the ecosystem around the technical topic you are writing about. Inevitably, this will give them a deeper appreciation and understanding of your content.
Created on 2022-08-05
Updated on 2023-05-25