WTFM: Writing Effective Software Documentation

Bad documentation can send me into a ranting tailspin because it wastes inconceivable amounts of time, costs real money, and makes us developers unproductive and miserable. Documentation might be bad because it is flat-out wrong (typos, references to an older version, etc.), but more often documentation is bad when it fails to tell us what we need to know. You will see that this is not entirely subjective.

What Documentation Requires

It’s an insidiously simple question, but there seems to be no “official” agreement on what constitutes required fare when it comes to writing documentation. It’s no wonder our software is unusable! So let me take a crack at it defining the requirements:

1. Examples. First and foremost, documentation requires examples. Everything else is secondary (yes, really).
2. A Feedback loop. Documentation must be able to evolve through changes suggested by its users. (This implies that you actually have users).

That’s it! Having these components does not guarantee that your docs are good, but without these two pillars your documentation (and by extension, your software) will be a failure.

Examples

You and every other human on the planet learned to speak by hearing nothing but example after relevant example. It’s not just children who learn this way: adults largely learn from example too.

Examples cut across all other learning types: if a student is a visual, auditory, or a kinesthetic learner, an example is what they need (and a teacher can cater to how to deliver it). From my own experience as a polyglot and a musician, I can testify to the efficacy of the Pimsleur language programs (which focus on repetition of relevant phrases) and the Suzuki method for learning to play musical instruments (which focuses on learning to play by ear).

Examples work! And software projects that scrimp on them are unnecessarily steepening the learning curve. “This documentation has too many examples!” said no developer ever.

When writing examples, keep the following points in mind:

1. Include a README that succinctly states what your software is and does. No README, no users: don’t waste anybody’s time.
2. Focus on tasks (not concepts). Why is a user here, using your software? What tasks might they need to accomplish? If your users need to download and install dependencies or activate a third party API token before they can use your software, then you should include examples on how to do that. Don’t be afraid to go beyond the context of your software: it doesn’t exist independently in a vacuum, so neither should your docs. It doesn’t help your users if you throw up your hands and say “that’s not my problem!”
3. Include variations. If you can use something in several different ways, then include examples that demonstrate those use cases; the juxtaposition helps clarify the purpose.
4. Put the examples where they will be seen. For functions, put the examples in the function documentation, for classes or modules, put the examples in the class or module documentation. Consider GraphQL: it integrates the API documentation within the API itself, in the most visible place. That’s a huge win! Remember the irony of “The Hitchhiker’s Guide to the Galaxy” where a critical demolition notice was “on display in the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying ‘Beware of the Leopard.’”
5. Include integrated use cases. If a single function or module isn’t really useful all by itself, don’t keep us in the dark: show us an example of how the pieces fit together to accomplish a common task. Know your audience and what they need to do.

Feedback Loop

A feedback loop may actually be more important than the inclusion of examples. Given enough time and “evolutionary pressure” supplied by users, documentation will evolve into better and better incarnations.

Consider Wikipedia: it is one of the most visited sites on the internet endeavoring to contain the entire breadth of human knowledge and it accomplishes this because it has a dead simple method for facilitating massive peer review (i.e. it has a very effective feedback loop).

For many software projects, the version control system (e.g. Git) is a convenient mechanism for achieving a feedback loop, but it is only useful insofar as it meets the following needs:

1. Allows for meaningful changes. Users must be empowered to instigate substantial changes (including the ability to add or delete content). Consider MongoDB’s documentation: their feedback loop is a total failure because users can only offer a star-rating on “How helpful was this page?”. Of course their documentation is bad because they chose to make it unfixable.
2. Is fast. The documentation must react relatively quickly to the feedback because feedback is only useful when it drives changes. Don’t wait to publish changes until the release of a new version, get the word out now!
3. Solicits feedback from all users (not just developers). This is perhaps one of the most difficult goals to achieve because it is so difficult to maintain iterative changes for documentation independently from the code itself. The convenience of in-line documentation (like Javadoc) often means that the feedback loop will only solicit changes from developers because only they have enough skill to navigate the codebase, so this point may require extra consideration!

Next Steps

Having examples and a feedback loop are only the starting points: there might be more to say about your software, e.g. explanations of its design philosophy or concepts, but just remember: this type of documentation is of a higher magnitude, so it has no place to stand unless there is a solid foundation in place. Too often the carriage is put before the horse when software authors detail their philosophical motivations behind the software and mistake that as “documentation” — it might be an interesting aside for another author seeking to write similar software, but such a chronicle does not tell the users what they need to know (i.e. how to use the software). Don’t let philosophical rambling obfuscate the examples that demonstrate the software’s practical usage.

Tutorials also must build on a solid foundation, and when tutorials veer too far into demonstrating basic use cases, it can indicate a deficiency in the original documentation or the lack of a viable feedback loop (or both). If you have ever had the misfortune of suffering the use of the Oracle database, as one example, you will invariably be directed to the website of some guy named Tom for the instructions on how to do virtually anything in Oracle — that’s a powerful indication of everything that is wrong with their documentation.

Conclusion

Don’t let all your hard work go to waste because you failed to communicate what your software is or how to use it. Writing stuff that computers understand is easy; writing words that humans understand can be considerably harder. I reject the notion that engineers can’t write effective documentation. Yes, technical writing is a skill, but providing examples doesn’t require much writing, and any developer can establish a feedback loop that solicits others to help make your documentation effective and useful.