Documentation

A lot of engineers procrastinate on documentation. Sometimes there’s just not enough time between upgrades, server failures, user requests, projects and the numerous other tasks an engineer must juggle to get the job done. But sometimes it’s just because no one wants to do it!

Documentation is key to keeping an infrastructure organized and in the end saves time and effort. Here are a few simple ideas for getting a documentation library started.

Share

Start a shared site for documents to be posted. A departmental SharePoint site is an easy way to get started. But if your organization doesn’t use SharePoint, there are several document sharing sites available on the Internet. Even a shared folder structure on a file server will do. The point is to put the documents in an easily accessible place.

Categorize

Decide what needs to be documented. Each organization will have its own set of requirements for what should be documented.

I find that an environmental overview document for each application or server environment is very helpful both for new engineers and for anyone troubleshooting issues in the environment. Having a list of servers, service accounts, database names, etc. at hand shaves much time when trying to work out an issue.

“How-to” documents are always welcome. How often are you going to install AD FS and if issues arise down the road, will you remember in six months what you did and why? If you write it up as you go along, you don’t have to remember anything because you can always look it up.

Troubleshooting documents pay for themselves many times over. Documenting an issue and its remediation is priceless. How much easier would it be to find the answer to an issue based on your specific environment instead of searching Google for someone with a resolution to a similar problem?

Standardize

Using templates can make documentation easier for everyone. There’s no need to reinvent the wheel each time you bring up a new environment. In addition, this can ensure that critical information doesn’t get left out of the documentation.

Update

Documentation is only helpful if it contains accurate information. Keeping documentation updated is critical to its usefulness. Documents should be updated regularly based on any changes to the environment. Additionally, documentation should be reviewed annually to ensure that it remains up-to-date.