There's a long running joke in IT circles.  In our hearts, we are all just very good at google-fu (the art of tactical googling).  It's impossible to know everything, so we've gotten very good at creating and hunting down instructions.  These instructions are compiled into tomes called documents.

Documents can come in many forms.  Video's, checklists, spreadsheets, and even Wikipedia style websites.  

As both a connoissuer and creator of documentation, I present to you a few rules to ensure your documents do their job. 

1. Keep it Secure, Yet Easy to Find: Do you know what’s absolutely useless? A repair document tucked away in the very hard drive of a broken machine that won’t power on. That’s like leaving keys in the car and hoping it never gets broken into or locked. Good documents need to be both available and secure.

2. Keep it Simple: Documents should be written so the intended reader can understand it. Don’t get me wrong, there are some dense specimens of humanity out there, that shouldn’t ever touch the blinky shiny light box. But documents should be written for people, not robots.

3. Make it Easy to Navigate: Good documentation should be well organized. There should be a table of contents, clear formatting, and a clear structure. Nobody wants to dig through a library after an earthquake, and nobody should have to do the same for complex technical documents either.  

4. Videos and Pictures Too: A picture is easier to understand than a paragraph. A video is easier to understand than a picture. In the day of the camera phone, there’s no excuse for lengthy, obscure, jargon filled tomes of nonsense. If I can choose between a 5 minute video and a 100 page novel, I’ll watch the video every time. 

5. Regularly Updated and Tested:  Outdated documents tend to do the opposite of their intended purpose.  It’s very easy to accidentally ruin your machine copy-pasting old commands. When a change happens, the documents need to change too.  It should also go without saying,  all instructions in a document should be tested and known to work.  

6. Open Source: Hear me out. You should be able to read your documents without paying for software to read it. You should be able to access it on your phone, your pc, your tablet, or your iMac.  You should be able to read your documents on just about any device without paying a middleman. To that end, ALL of my documents, videos, and photos are created in open-source formats. 

7. Have Clear Warnings: Look, there are some things that just shouldn’t be touched by unqualified people. It’s very easy to wreck a system playing around in the command prompt.  That’s not to insult your intelligence, it’s to keep you from having a very bad day. A good document will spell out very clearly who should be using it, and who should not. 

-B