While it may seem burdensome to have to sit down and document everything necessary to support your environment, trust me when I say it is much more of a hassle not having it when you’re in a pinch. Conversely, if you’re working with outside parties for projects, be sure to insist you get proper documentation before, during, and after.
What sorts of things do you want to document? Well, any plans, processes or diagrams that someone may need in order to manage or maintain your environment when you are not there.
Where should you start? The best place to start is where your network starts, your internet connectivity, firewall, data flow, IP Schema. Create a flow chart and print it out and keep it easily available — maybe even keep a copy on the wall. Next, work through your authentication and data access such as physical servers, domain controllers, DNS, DHCP, iDrac, line-of-business applications, backup and recovery. Finally, your warranty, contracts, vendors, and general contact information.
You want to document how your infrastructure is built and maintained. If you were “hit by a beer truck,” what would someone need to know to step in and handle your job today? Anyone should be able to walk into your environment, use your documentation, and have a good understanding how everything is set up. It is also important if you ever want to take a vacation without interruption.
At Mirazon we always make sure we properly and completely document the projects and work we do for our customers. We are also available to due peer reviews of the documentation you already have.
Documentation Do’s and Don’ts
When writing up your documentation, here are some good rules of thumb to follow:
Keep them broken down in separate documents by level of detail. You need some high-level overview documents and separate documentation for the nitty gritty of each server and applications. Make it easy to find what is needed and not put so much info in a single document so that it becomes unmanageable.
Only include the important, pertinent information. If you make your documentation too exhaustive, you or someone else may not ever actually read it and then you’re making it far too cumbersome to keep updated. Out-of-date documentation can be worse than none. Leave out the unnecessary – don’t waste time documenting every DLL or the same executable program on every machine.
Don’t include passwords in your documentation. While you want someone who picks up your documentation to have a good understanding of how your infrastructure works, you don’t want it to be the proverbial keys to the kingdom. Hopefully you’ve got a procedure for password documentation, like using a program such as LastPass, or you store them in a secure area somewhere.
Have your documentation peer reviewed. Just like your seventh grade English teacher has always said, having a second set of eyes on your work can help reveal errors you overlooked. Have your peer check for completeness and typos. You don’t want a mistyped IP address – that could cause some serious issues! Plus, a peer review can help you discover a vulnerability or issue you overlooked (it happens to the best of us).
Don’t keep it to yourself. Sometimes we hear that documentation of the systems are not shared or created under the belief that keeping this information close to the chest is job security. We can assure you that is more likely to be your downfall than your saving grace. As an employee or contractor, it is their information and their data, therefore making it your responsibility to provide it to them.
Tools
There are a lot of tools out there you can use to trace your infrastructure and configurations that will help make your documentation endeavors easier. The important thing is to know the applications you use are trusted. Don’t just download the first freeware you find. Know what you are using is legit, legal, and safe. Read the EULA — many such applications are free for home but not corporate use.