Path to successful documentation

Ah, documentation. The stuff that people supposedly neither read nor write. Well, this last bit is not completely accurate. People who can get by without reading documentation do so, but when you are stumped the documentation makes the difference between using a product or a service or not.

No matter how many features something has, or how good it supposedly is, if it does not work for you you can't use it. Bad documentation eventually costs market share.

Today though I want to talk about documentation in corporate setting, especially internal documentation. Lack of documentation in companies seldom means that some product will not be used, although it is certainly possible. More likely whoever has to use it will spend a lot of time figuring out how it works. Looking at the company overall, if no employees write documentation for anything and then all employees spend a lot of time figuring out how everything works, it should be obvious that such an arrangement is inferior to everyone spending a little time documenting what they are doing and saving a lot of time figuring it out. It should be non-contentuous that explaining how something works takes a lot less time than figuring it out for non-trivial problems.

First, let's look at how not to handle documentation.

Word of mouth

In this arrangement, there is no written documentation at all. If Bob needs to know how something Alice built works, Bob walks over to Alice and asks. Bob does not write this down either. If Charlie takes over Bob's task, he would have to either talk to Bob or to Alice to figure out how to perform the task.

A version of this arrangement is popular with managers/bosses in some corporate cultures, where the boss gives verbal directions to their subordinates and expects subordinates to "ask questions if anything is unclear".

This style of managing documentation, if it can even be called that, is the most wasteful.


This style is similar to word of mouth, but now Bob would email Alice and Alice would compose an email back with instructiors and maybe an example or two. Later when Charlie takes over, either Bob or Alice could forward Alice's initial email to Charlie and save themselves the time a word of mouth explanation would have taken.

You can already see how this is an improvement over the word of mouth style. But email is not that great:

  • For complex projects there is no single email that has all relevant or important information. The more complex a project, the more emails would have to be written to adequately explain it all.
  • For projects under development, even though functionality gets discussed and there are emails about it here and there, those emails are not of "digest quality" - they may refer to things that no longer exist or have been redone, and each email is very short so reading them all would take prohibitively long.
  • The more emails have to be forwarded, the easier it is to forget and omit a bunch of them.

Word documents

This is not something I have a lot of experience with personally, thankfully, but I imagine less technology-oriented companies use these a lot. A predecessor to google docs, if you will. I wish I could title this section "word processor documents" but people to whom it applies would probably get confused as a result.

Word processor documents are larger than emails and can consolidate knowledge. They are also editable (meaning revisable), unlike email which is immutable once sent. A word processor document would therefore likely be more comprehensive and accurate than an email.

Google docs

This is probably an emerging standard in the somewhat-technical businesses of today. Being on the internet, google documents can be edited by multiple people much more easily than word processor documents.

Google documents have all of the benefits of word processor documents plus ease of collaboration. Thus they are a step above word processor documents.

However, google documents are not the pinnacle of progress for more technical users. Living in a half-proprietary system (you can export the documents but all operations are done using a proprietary system) there is one way to edit the documents, one way to search them, one way to view them. Suppose you want to run a regular expression search on the entire body of documentation you have, how would you do that? What if you want to search for common words that are also used in a unique context and want to rapidly skip through lots of irrelevant hits to find the ones you are looking for? Web interfaces are notoriously poor at solving that particular problem. While many people would stop at google docs, we don't have to.


Markup has most of the advantages of a proprietary document system and nearly none of the disadvantages. Collaborative editing, viewing on the web, and search are all there. But if you can download the source files to your computer you can use any tools you want on them to pretty much do whatever you want. You can compensate for poor online search capabilities (Python still leaves a lot to be desired in this regard, for example) by searching the documentation offline yourself. You can view the documentation offline in the first place. And so on.

Systems that use markup but are only usable via the Internet, like wikis, are halfway to this goal.

Growing documentation

OK, now that we settled on a documentation format, how does documentation get written? Here is a simple rule that can work in almost any situation you can think of:

Instead of sending an email, instant message or explaining over the
phone, commit the text of the explanatino into the documentation
system and point to it.

Writing a coherent manual is going to take more time than sending an instant message, but the manual will have higher quality. A well-crafted email can approach the quality of standalone documentation, so why not take a few more minutes and do the job right?

Starting documentation process

Starting documentation writing from scratch is daunting. It is always easier to add more documentation when some already exists. Start the process when you begin work on a project by following the second rule of documentation:

If you receive an email with setup instructions and there is no
official documentation, convert the email into the first
official document titled "Getting started".

Converting a plain text email into organized Markdown, for example, should not take long. Then, follow the instructions in the converted document and verify that they are correct. If they are not and you ask for additional assistance, update the documentation you wrote. Before long someone could spend 5 minutes reading the getting started guide and get a pretty good idea of what the project consists of, how the pieces fit together and maybe even how they work.


Memory is always inferior to written word when it comes to keeping records. Yes, there are 10 people in the world with photographic memory, but even memory champions are tuned to remember certain types of information like sequences of cards. Show them the manual for your project and chances are they won't be anywhere near as good at memorizing it.

Speakers at conferences prepare notes for 5 and 10 minute talks. Is documentation for a typical software library, never mind a framework or a complex application, going to fit into 10 minutes of talking time? Not even close. So how can anyone expect to magically remember everything important when they are asked how their software works?

Lookup time

There is a difference of orders of magnitude between looking something up on the Internet and asking a person. An internet search takes seconds. Asking a person takes minutes over instant messenger, minutes to hours over email, a day if you are unlucky, and it is not exactly uncommon to never receive a response, even for queries within a company. While you are waiting for that response you might not be able to do whatever it is you have to do. The "just ask me questions" approach tends to ignore this cost of asking questions of human beings.