Bounding Unicorns

How To Introduce 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.

Email

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 docs have their issues. They are:

  • Not well organized - while google docs do have a folder structure of sorts, documents generally start out on the top level and frequently stay there.
  • Not discoverable - often the documents are created by individuals, even when using an organization's G suite, and only shared with specific people. Newcomers don't know that the documents even exist.
  • Not crosslinked - partially this is a result of the lack of organization, partially lack of good tooling to hyperlink from one document to another, and partially the people who use google docs, being generally less technical, tend not to consider crosslinking. Whatever the cause most google documents I've come across are read in isolation from other related materials.

Markup

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. In addition markup tends to favor building up document collections rather than individual documents, which ends up increasing both size and quality of documentation. Markup-based systems also permit arbitrary file attachments.

Wiki systems like Confluence and code-based tools like readme files both qualify under this section.

Growing documentation

OK, now that we settled on a documentation format, which is typically either something like Confluence, in-source documentation or google docs, how does the documentation get written? Here is a simple rule that can work in almost any situation:

Instead of sending an email, instant message or explaining something over the phone, commit the text of the explanation 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. Once the centralized documentation repository has some content, adding further content gets easier.

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.

This works for Github repos as well as onboarding documentation. Most good companies won't object to someone new beginning the documentation effort.