What vs. Why

Documentation: Saying the word makes most geeks cringe, cry, or run to the comfort of the datacenter for safety. Aside from hating to write it, there's a perception of "What do I need to document for? I know what I did?!".

First answer: No, you probably don't.... but that is really the right answer to the wrong question. Knowing exactly what you did is only about 20% of the value of documentation. Yes, if a clear "Click this, click that" process is provided it's somewhat reasonable to expect that an installation or configuration be done consistently... but much of this can be fixed by using a well managed and stored command-line installation process.

Think about a different question though. Think about how many times you've asked the question "Why do we do it that way?" or "Why is it like that?" or even "Why should I configure it like that?" (despite what is listed in the installation scripts). The truth is that "Why" is much more important than "What". Even as you document the configuration you're implementing, you're doing it based on information that you have at that moment... information that others may not have or understand, and information that not even you are likely to remember a year from now. At that point someone (or again, even you) will take a look at your process and make a change thinking "that's not right" only to have the environment break before your eyes, or worse, create some cascading effect into other systems that cause them to fail as well.

"Why" is what creates the "What". If you correctly document why you're making a decision, you're providing an opportunity for others to understand the configuration well beyond simple button-clicking or script-running. You're helping people understand why the decisions you made are good ones, what options shouldn't be changed, what options can, and how to better interact with and manage the environment. More often than not, if you clearly document why, you can rebuild the "what" later... because all of the reasons that led you to a conclusion in the first place are clear.

So, as you're writing your documentation, consider writing these things down at a minimum:

• The page/screen/command being run
• The options/parameters being selected or provided to that screen
• A capture of the screen with the correct options selected
• The reason this was the correct option or setting in your environment
• The output or outcome (if available) of the command if it was executed properly.

A year from now when you're trying to remember why on earth you made this obviously bad decision, you'll be glad you wrote it down... and glad you didn't break your entire intranet portal in the process. ;)