Blog Home RSS Kelvin Jackson

Writing Documentation, or: Why I Keep Reimplementing Basic Utilities


There would be less duplication of effort in the programming world if more programmers were better writers.

While programmers are good at writing code, they are often quite bad at writing human-readable documentation and/or instructions for using said code. Thus, although there are exceptions, interpeting the documentation of an open source or relatively underfunded software product well enough to use it effectively is often a real challenge. The ultimate result of this is that when I need some bit of functionality in my code that an existing library might provide, I often end up reimplementing it myself, even though a solution is out there — because writing up my own solution takes less time than poking, prodding, and learning my way around the existing product.

Now, things really don't have to be this way. Programmers aren't stupid — most of them could be better writers if they put in the time to learn how to write good instructions and documentation. This doesn't mean trying to become the next Gogol or Shakespeare, but it does require paying attention to the context your audience has versus what you have, and whether or not they will know all the things you know about your product (spoiler: they won't).

So, the next time you're writing documentation, imagine that your audience is a complete novice. Don't talk down to them, of course, but don't assume they know anything more than how to issue shell commands, programming ability in the abstract (not necessarily in a particular language!), and easily discoverable facts. Notably, your reader does not know what other software or libraries you have installed on your computer (but that you might have forgotten to list as a dependency), or the details of your product's API. Also keep in mind that the principle of least surprise only gets you so far so far: you should try to make your user interface as unsurprising as possible, but recognize that some users will nevertheless always be surprised — so make sure you tell them how it works!