I’m crazy about documentation. More than that, I’d call my self a "Documentation Guy". Not only do I go through extra steps to document all technical and process decisions for the systems I control but I also hound the people on my team for documentation that in a round-a-bout way impacts my space. Why am I like this? A couple of reasons, some are selfish and others are not. Let me explain.
Good documentation is a crucial piece of a solid IT organization. I didn’t always believe this and would be the guy saying "Who’s going to read that?" Problem is I would move onto another project and bam, something would happen and screw up a configuration I made in the past. No one knew what I did and usually there wouldn’t be time to figure things out because of these critical business applications needing to be online. This brings me to my first point:
Point #1 – Good documentation allows those that will be maintaining your systems later on to know what you did to set them up
This is probably the biggest impact that good documentation can have on you. Wouldn’t it be terrible if you are now part of the Domain Administrators group and while on vacation you get called because SMS is down and no one knows how you set something up? Of course documentation, and more specifically detailed documentation, also gives back to the company and others knowledge that you have acquired through training and experience on the job. For any organization to progress and move forward they need to minimize the learning curve that new team members have. If processes, procedures, and technology implementations have to all be relearned whenever a new person joins a group then they will have to work just as long or longer to get to the point you are at. Which means that:
Point #2 – Good documentation helps an organization progress long after you have left
This point is largely about the long term benefit you are giving to the company however it also has a certain level of satisfaction to it. Personally I want to know that the work I did for a company was not all for nothing and lost after I left. The best thing that I can do for my legacy to be carried out is to document the thoughts and ideas that went into building infrastructures along with the technology because this ensures not only that things are done right but that the people doing them know why they are.
Point #3 - A sysadmins memory is usually lousy
We all need to reference not only what we did but also what others did later on in life when making changes or implementing either a new technology and/or process. How can we do this without documentation? Anymore its becoming a rarity when all you do is one job. Because of this everyone forgets something they did in the past especially when it comes to technical configurations. Document it well and you'll save yourself headaches in the future.
Point #4 - You have to know what you are talking about to make good documentation
I've met a lot of really smart people over the years and hands down the one quality that the people I'd refer to as "guru's" have in common is good documentation skills. They have to know what they are talking about in order to put technical thoughts down on paper. Documenting things almost always leads to a deeper understanding of a product or technology. Take your SMS infrastructure for example: If you are documenting how your site will have NLB configured as your Management Points you'll start asking questions about how the process flow works and answer them before anyone else does. How does NLB disperse traffic between the Virtual IP and the different hosts participating? How do clients know how to go to that Virtual IP in the first place? What happens when one of the hosts goes down? Once you start asking these questions and doing the research to answer them you will be able to speak with authority on a multitude of subjects.
Point #5 - Complex systems need to often be set up in a repeatable manner
When your dealing with something as complex as Domain Administration or a Systems Management product many times you will be asked by management to roll out a new environment in a very short timetable. The thought here is you've set this up once already so its cake to bang out a new environment right? When doing something like this there are often dozens if not hundreds of steps involved and the fastest way to accomplish them is to follow appropriate steps in the correct order. Good documentation here will save you trial and error time by not rooting around for product or system requirements as well as other dependencies you accounted for in the past but don’t have the time or resources now to research. A perfect example of this are server builds. Even if you have an imaging process in place there are often post setup tasks that must be done to ensure that systems are configured on the network properly. How about all the IIS configuration for SMS 2003? Instead of figuring out later on why you are having some DP issues with BITS, follow your documentation on how to set this up correctly in the beginning and save yourself the headaches down the road!
How should people get started with documentation? I actually don't think its always the best to start documenting policies and high-level architecture if you don't have much experience with documentation in the first place because chances are the results will be weak. Do you help out your desktop guys a lot with troubleshooting a specific application or network problem? Try documenting what your process is to resolve it. Go DEEP into detail! Call out explicitly in your documentation who your intended audience is and give an overview of what your documentation is trying to accomplish. Always include the ability to update it later with versioning, author(s), and track changes clearly listed for others to reference in the future (please, no jokes about documentation inside of documentation). List out your steps and remember that the people following them will most likely be technicians and not Engineers or Sysads. Fear not screenshots - they are your friends! Don't skimp out on the good stuff either such as Conclusions and where to go for help if the documentation doesn't prove effective for everyone. And if possible always include references or links to more information to those interested.