Document This!?

When it comes to technical documentation, most people don’t want to even think about it, let alone spend the time it takes to make it effective. I get it, and frankly it’s not one of my favorite things to do either. So given that, why do we bother to do it? Because when it is done well, it is incredibly necessary, valuable and useful. I hope to give you some guidelines for why it’s useful, and how best to achieve it so that it will seem less daunting to you the next time you need to do it. And since I’m writing documentation about documentation, hopefully I’ll follow my own advice! How meta of me.

“Letting institutional knowledge live only in your own head is poor leadership. Document!”

Technical documentation is important to the success of a software product because it can:

1. Describe what the product does, and what problems it solves

2. Allow other software developers to onboard to the project much faster by understanding how the system is built and fosters communication in common terms

3. Provide motivation behind design decisions and spurs architectural discussions

4. Provide information to end users about the product and what it can and cannot do and how to use it and what to do if they encounter problems

5. Mitigate the “hit by a bus” problem, where a dangerous amount of institutional knowledge resides in one person’s head

In my experience, though, most companies fail to provide adequate documentation for their products. It’s rare that software is praised for its documentation. When it is praised, it is often only for having any documentation, since most don’t. The three most common reasons I have found for this are:

1. There’s a lack of distinction and clarity around the different types of technical documentation that exist, and when each should be used.

2. Documentation is not a part of the product development process; it’s an afterthought and is treated as such.

3. Companies (especially start-ups) often do not source a lot of experience in how to create good technical documentation.

So let’s address each of these common failings by answering a few questions:

Question #1 - What types of technical documentation exist and when do I use one vs the other?

“If you have to provide a step-by-step walkthrough, you’ve built the wrong product.”

— Ancient Tech Proverb

• Internal Documentation – This is code and development documentation, architecture documentation, or internal-only feature documentation. This is used by developers and/or testers, and is vital to quickly onboarding additional people to a project. This type is the most often neglected as many developers think that comments in the code are sufficient for this, but a new person to the project often needs a more macro view of the project, which this documentation can provide.

• Troubleshooting Documentation (aka RunBooks) – What do we do when a failure happens? Where are the logs and how do we read them? How do we turn on or increase logging and/or debugging?

• API or SDK Documentation - A list of all the API or classes/method calls that the software provides. The most successful way to do this documentation is via an automated tool that ties the documentation directly to the code otherwise this documentation gets out of date very quickly. There are many such tools, but Doxygen and Swagger are two of the more popular ones.

• Step-by-Step Walkthrough – There’s a saying that goes, “If you have to provide a step-by-step walk through, you’ve built the wrong product.” I agree with this in principle and think that good design and user experience practices can mitigate the need for this type of documentation. However, if the product you are building is overly complex, this documentation may be appropriate.

• Product feature documentation – This is a list of all the features and settings in a product: what it is used for, and when/why one would use it. Many products use their help or functionality to link to various parts of this document. As new features launch, this documentation is updated, and usually a reduced version of this is used in the launch notes for the feature.

• Knowledge-base, Frequently Asked Questions (FAQ), and Forums - Documentation here is usually a list of problems or questions with the associated answer. The goal of this documentation is to only have to troubleshoot an issue once, and then provide the solution so that any subsequent occurrences can be easily solved by anyone who encounters them.

• Blog post - Something informative that’s based upon the writer's real life experiences. Blogs are often used to generate interest in a company or spread knowledge to a broader audience than the above types.

Question #2: How do we ensure that the appropriate documentation actually gets completed for each new feature or product?

“Documentation is most effective when it’s part of the product development process.”

The most effective way to do this is to incorporate documentation as a part of the product development process. Much like there is a “Build” stage or a “Review” stage, make a “Documentation” stage, and a product is not considered completed until it is done. When the product or feature is first being scoped out, decide which of the types of documentation listed above will be necessary and make their completion part of the “Definition of Done”, and most importantly, part of the estimation of the project. Also, when errors occur or questions come up, be sure that a part of your process is to add them to your knowledge base, FAQ or forums.

Question #3: Now that we know what type of documentation there is and how to make it part of the process, how do we actually create excellent documentation?

Since each type of documentation varies there will be some specific distinct strategies that will work best for each of them but I will give you some rough guidelines that will generally apply to most of them.

1. Know your audience

Writing effective documentation is really all about making sure you serve the needs of your audience. Most important is to know who your primary audience is. So before you begin writing, it’s worth finding out who your audience is and what, exactly, it needs.

2. Talk to the reader, not at them

Don’t just fire a bunch of information at people; remember that the most effective documentation will feel like a conversation. Make sure your reader knows that there was a human on the other end of the creation of it.

3. Be very clear at the beginning what you want to reader to get out of the document

For example, at the beginning of this post, I mentioned that my goal was for you to feel like you have an understanding of why documentation is useful and how to achieve it.

4. A picture is worth a thousand words

When appropriate, nothing can speed up a reader’s understanding of a concept better than a smart illustration. Just be sure to provide appropriate context and caption so that the reader isn’t left trying to figure out what the image is about.

5. Avoid vague pronouns

Vague pronoun references are one of the most typical causes of confusion in technical documentation. For example, take the sentence, “The API has a security vulnerability that is difficult to detect. It has caused others problems in the past.” What is “it?” The API or the vulnerability?

6. Create templates

Create templates for each of the above types and follow them. This consistency makes it easier for the reader to know what they are reading before they get too far into it.

7. Make it look good

Ever look at a document and notice that the fonts for a bulleted list are the wrong size? Or that the indented material is inconsistent? Even if everything you put in the document is correct, if the document doesn’t look good, it immediately loses credibility in the eyes of the reader and those mistakes distract from the information you are trying to convey.

That’s it! See? That wasn’t so bad. Now go and document something… the person that comes after you will thank you.

Jason Bennett

Jason is the Chief Technical Officer at Crisis Text Line.