Writing good documentation is a skill that needs to be learned and practiced just like writing good code.

While code talks to other code, documentation is your chance to talk directly to the user. Embrace documentation, after all, it will be looked at more than the code it supports.

This entire repo is documentation, so this document serves as a guide about how to write for this repo as well as for project documentation. This guide mostly deals with technical documentation, but is intended to be applicable to all types of documentation you might write at Vokal. Portions of this document will refer to the subject of documentation specifically as software, and other portions will speak more broadly. Disciplines should still maintain standards that are specific to documentation types with which they work.

What is Good Documentation?

Bad Docs

Everyone has experienced bad documentation. Bad documentation leaves gaps in the purpose or use of a tool, leaves questions unanswered, or is simply unclear. Bad documentation leads to misunderstandings, frustration, and mistakes. Bad docs talk past or over the reader instead of to the reader. People don't like using tools that are documented poorly. Likewise, documentation that readers don't like using, regardless of their background, should be considered bad documentation.

Types of Documentation

Anything that someone needs to learn to be effective at a task should be documented. You can document any standardized procedures or practices, and any knowledge that benefits others.

Often, a long email going out to a bunch of people is really documentation. Consider putting that information somewhere more durable and reusable than an email and just sending a link to it. Now, instead of a horrible wall-of-text email nobody wants to read, you have proper documentation that can be iterated and improved.

How to Write Good Docs

The biggest challenge authors face in writing good documentation is writing it in a way that is understandable for the broadest audience. Your audience might be senior engineers, but it is more likely to be people with less experience and background knowledge.

Why People Read Documentation

Most readers will be looking for whether the documentation can solve a problem and then how it can solve the problem.

If you think about browsing search results on Google or Stack Overflow, you first try to determine for each result if it is relevant to your issue. It is a waste of time to try out solutions that don't seem to address the problem you have. It is important that documentation state clearly what it covers or solves before getting in to further details.

Don't Assume Prior Experience

When writing documentation, the author is effectively the subject matter expert. Authors should never assume that readers will find anything they write obvious. Believing something is obvious is a judgement of the reader's skills, and writing to that assumed skill level indicates some users are not qualified to read the documentation. If you are documenting something that requires previous knowledge or experience, you should clearly state those requirements.

Writing good documentation requires the author to empathize with their potential readers knowledge, experience and background.

Answer Common Questions

Try to format documentation in a way that makes it easy to find answers to the most common questions.

Educate Readers

Genuine innovation solves problems that are not obvious. So, the more innovative a subject is, the more documentation needs to elucidate the issues it addresses before it can explain how it is solved. There needs to be bridge between what readers know already and what they need to learn. Authors can't jump from 1 + 1 = 2 to calculus and expect readers to just fill in the knowledge gap between those things. Authors may need to link to external sources for reference, or to explain concepts within their documentation.

Request Reviews from Diverse Readers

To avoid writing to an assumed reader type, authors should ideally request their documentation be reviewed by a subject matter expert and another person that is generally unfamiliar with the topic.

This is somewhat different than recommendations at Vokal about code reviews because code reviews are almost entirely about ensuring logical correctness. Experts will be most effective at ensuring logical correctness. Documentation reviews are also about how effectively documents communicate with a diverse range of human beings with different backgrounds.

Review by a subject matter expert will find flaws in the factual content of the documentation. A reviewer with less expertise on the subject matter can point out where the docs are unclear or new terms need to be explained.

Open Source

When publishing public projects, the documentation author needs to write documentation to an even broader audience than when writing for readers at Vokal. We have certain practices and knowledge within Vokal that make certain things obvious to us, but may be entirely unfamiliar to people outside the company.