radicaledward101

3 Qualities of Good Documentation

For documentation to be good it must meet all three criteria. Failure of any of the three indicates that the documentation is fundamentally flawed. It may be costing you or your organization much more than the time and energy spent producing it.

Content Quality

First the document must accurately communicate information. It should be up to date when written and updated regularly when the underlying information changes. Its format should be highly legible, actionable and referencable. Checklists (read The Checklist Manifesto!) and recipe-style documents hold the most value. These can have links to deeper explanations when needed. Multimedia options should be provided for initial training but never used for quick reference.

Poorly written documentation that is easy to find and on-topic is highly damaging. It may mask better, less discoverable docs. It may mislead the reader, potentially even permanently. It may cost significant time to interpret.

Relevance

Second, the documentation provided must be relevant to the group maintaining and using it. Old documentation should be archived, purged, or hidden in such a way that it does not distract from more relevant information. New documentation should be similarly hidden until it is complete and ready for consumption.

Well written, off topic documentation that is easy to find is worthless at best and a time sink at worst.

Discoverability

Finally, good documentation must be discoverable. It should be possible to find it quickly and easily. There should be no ambiguity that it is the correct document for its purpose. Deduplication, tagging, search engine optimization, and manual curation should all be performed to ensure that the documentation gets to the people who need it as seemlessly as possible.

Even the best written, most relevant documentation is worthless if no one can find it.

How do we get there?

The short answer is librarians.

All of the activities of the modern librarian are necessary for managing an information repository of adequate size to have value. Some of these activities are

As the size of the knowledgebase increases it becomes more and more likely that this needs to be a full time job, or even a dedicated team, or group of team’s jobs. For the individual, this is more of a role we take on from time to time. Building a Second Brain has some great strategies for individuals.

For larger organizations, there is no replacement strategy for a dedicated role. This is in part because of power issues.

Librarian power

To be successful, the librarian role must be invested with the authority to create, move, change, merge, and, most importantly, archive or delete. That authority goes beyond something coded in software. To function the librarian must be able manipulate the documentation through pushback from individual teams. What is best for one team is often not what is best for the company.

Deduplication and culling can be frustrating for the creators or maintainers of affected items. This is especially hard when making the switch to an actively maintained system from an ungoverned one. The librarian must have the backing of leadership to implement and enforce these changes.

The librarian role must also be given an adequate budget to purchase, either externally or internally, new documentation to fill known holes. These holes may be discovered through activities like polling, search engine analytics, or newly announced process and technology changes.

Without these powers, the librarian will be unable to create the benefits of a well maintained knowledgebase.

The “save everything” problem

One of the biggest problems that a lack of active maintenance creates is the “save everything” problem. This is something that I am guilty of myself. It is hard to get rid of stuff if you don’t have to.

This type of failure is most easily seen in many corporate wikis. Anyone can create more docs, but no one is invested with the librarian’s authority to remove documents.

Saving everything creates problems in all three categories: discoverability is impossible because there is too much to sift through, relevance is questionable, quality is all over the place.

Fallout from failure

If discoverability, relevance, and content quality fall off, users will cease to use the system. They will stop reading it and stop submitting to it. Why write documentation that no one is going to read? Why read documentation that might be years out of date?

In this state, everyone falls back on memory and word of mouth. In the corporate world, this is referred to as tribal knowledge. This information is fragile and decaying. I know I forget all kinds of things. People leave my company all the time. We will lose this. It is worth the investment to fix this problem.

Call to Action

Start working on actively managing your information. If you are in charge of an organization, big or small, find a way to introduce, adequately fund, and invest authority in, the librarian role. Unlock the benefits of good documentation - faster training times, fewer mistakes, and higher productivity.