One of my favorite videos on the internet is this one by The Onion. It satirizes how Americans are complicit in the waste of many resources (in this case, money, soldiers, and energy). Unfortunately, the video reflects the experience I frequently have writing technical documentation in groups.

A problem is encountered. The problem is solved through trial and error. A discussion is had about how to solve the problem quickly the next time. Much time is spent writing a beautifully formatted multipage guide on how to solve the problem. The document is filed in the author’s favorite spot for storing documents.

The problem arises again. The technician responsible for solving the problem looks in all 5 places they think the document could be, but cannot find it. The technician asks the whole technical team where the document might be found. The team is not sure, but knows that the technician currently on vacation probably wrote it. The problem is again solved through trial and error.

I’m not sure how to eliminate this issue completely, but here are a few ideas I’d like to try:

  1. Write meta-documentation specifying exactly one storage location for each type of knowledge
  2. Eliminate hiding spots for documentation by locking folder permissions and hiding unneeded categories in IT knowledge management systems
  3. Write documentation in plain text to speed up the process and banish temptations to fiddle with formatting
  4. Ensure the full text of every piece of documentation is rapidly searchable within the Doherty Threshold
  5. Make the process of creating and retrieving documentation low-friction (fun) by eliminating ambiguity (and the anxiety that comes with it) in the documentation process