Encodo White Papers: Document Everything (2017)

Good documentation is part of every piece of quality software. What do we mean by “good”, though? Or “documentation”, for that matter? Quality software should be self-explanatory, but don’t be fooled into thinking that you don’t need to write documentation.

Actors & Use Cases

Documentation has an audience. Before writing anything, consider who you’re writing it for. What are the possible audiences?

Evaluators

Evaluators are interested in what your software does, how it interacts with other software, its performance characteristics, system requirements, the product roadmap, open issues and so on. If you don’t document your software sufficiently, an evaluator won’t purchase it in the first place.

By “purchase”, we mean that an evaluator will decide to use your software. This applies not only to commercial projects, but also to open-source freeware or even internal company software, be it a potentially time-saving Excel spreadsheet, a set of common UI or server components or an enterprise-wide multi-tier application.

Installers

Installers are interested in the basic installation options/paths and how to get from purchase/download to running. Here you need to find a balance between getting them up and running quickly, but also informing them that there is more to your product than just the standard rollout. They need to know that they can get set up efficiently but also that they’re not locked in to a single way of doing things (unless that’s what you’re selling).

Customizers

Customizers are advanced installers: they want to know how to tweak or customize an installation to meet their special needs. These are often the same people as installers, but

New Users

New users are going to use installed/customized software. They want to not only know what your software does, but how they can use it for these standard tasks. They are interested in underlying concepts in both the application domain and the user experience. They need both introductory and high-level documentation, with meticulous, step-by-step instructions. These users are likely to navigate documentation in a progressive manner, reading from beginning to end.

Everyday/experienced Users

Everyday/experienced users aren’t generally interested in introductory documentation. They are interested in how to become more efficient with your software. They will jump around in the documentation, using a search function to find what they need.

Extenders

Extenders are users—usually developers—who will be using your software as a building block, integrating it with other software or extending it to meet their needs. These users are interested in command-line options as well as descriptions of available APIs. If the API surface is larger, then functionality should be grouped and examples included to demonstrate how to use the various calls in common workflows.

Developers

Last but not least, you have to document for developers. That means writing your code and documenting it in a way that is understandable not only to you but other members of your team. Future members of your team, will also need to get up to speed. As is often the case, you yourself will be one of those future developers, when you come back to a project or product after a longer absence. Your future you will definitely thank you for leaving well-documented clues.

How to get started

Wow! That seems like quite a lot of documentation to write. It is. As with anything else, you’ll have to prioritize. We can make a list of the various documentation types we have at our disposal and identify the actors that would use them.

• Description/purpose (evaluators)
• System requirements (evaluators, installers)
• Readme (evaluators, installers, customizers, extenders)
• Concepts (all users)
• Tutorials (users, extenders)
• Training Videos (users, extenders)
• Error messages (users, developers, extenders)
• Command-line help (installers, customizers, extenders)
• Code documentation (developers, extenders)
• Log messages (developers, extenders)
• Issues/stories/bugs/todos/roadmap (evaluators, developers, extenders)

As you can see, we consider anything that helps actors to understand the software to be documentation. That means that writing useful error and logging messages is also an important way of documenting the product. Similarly, a clearly defined roadmap with stories/bugs/todos provides context for evaluators and developers. All of these forms of documenting a product can save everyone a lot of time, money and confusion by offering context-sensitive documentation right where it’s needed.

This extends to everything in your software or product: the best documentation is a good design. If the UX is more intuitive or command-line help is clear or the APIs are consistent and well-organized, that can go a very long way already. There is less need for extensive tutorials explaining each and every task when the product documents itself.

For example, if you name an API getUsers() and an input variable includeAdministratorUsers, then you don’t need to write much more than “Gets a list of users, optionally including administrators.”

For those reasons and many others, we recommend getting started early with documentation. If look at the list above, that’s kind of obvious advice.

• If you don’t know the purpose or the concepts, then you shouldn’t be building the product yet.
• You need to document how to set up and install the product or your own developers won’t be able to work.
• If error and log messages are obscure, your developers and supporters will lose a lot of time and money on issues and bugs.

Most importantly, the simple act of trying to describe what you are making will lead to a better product. You’ll often find that, as you document, you’ll notice things that could be done better or more intuitively or more consistently or more easily. The simple act of trying to explain what you’re making leads to a better product. If you find it relatively quick and easy to write documentation, then there’s a good chance that you’ve managed to build quality software.