I spent half of today trying to track down the server hosting one of my clients websites. The business and website have been around for so long, and the site maintenance and development has changed hands so many times, that the business owners have no idea who hosts their website, nor whose account controls it. The world won’t end without this information, but until I get it, their website can never be updated, and I can’t implement any branded email for that business. Basically, nothing can change.

I’ve preached the gospel of documentation before, but for you fellow IT technicians, I thought I’d give some tips.

In my experience, those in the IT field tends to have stronger math skills than language skills, so technical documentation doesn’t come naturally to most. But the fundamental importance of documentation cannot be overstated. And although technical writing is a career in itself, it is a skill that should be cultivated by every IT pro.

Servers are probably the easiest place to start. In a busy IT environment, a lot can change in a short period. To avoid the impression that you’re laying track while trying to catch a moving train, start with something that doesn’t necessarily change so quickly.

Clean Up First

Sometimes businesses grow so fast that the infrastructure doesn’t have time to be tidy. One client that comes to my mind was so overly complex that the only way I could even fathom beginning to write documentation for was to start consolidating things. There were four different internet connections and gateways, each with their own configuration. I replaced those with a single, 4-WAN-port router. There were also two different fax servers and two NAS devices, none of which worked properly. I culled the herd until the infrastructure made sense again and from there I could rebuild.

Ask Questions Like Your Life Depends On It

The devil is in the details. Capture everything you can. And I mean everything – even down to the date of deployment and hard drive serial numbers. That can save a lot of time down the road to determine warranty status, or to schedule hardware upgrades. If there are any quirks or special considerations for a particular piece of hardware, include that in the notes. A proprietary piece of software? Include it. Does it have RAID? How is it configured? Is the drive partitioned? How? Is it backed up? When and how? Are notifications sent out upon success/failure? To whom? Most importantly, what roles does the server fill? Domain Controller? File, web, or database server? DHCP? DNS? VPN? E-Mail? Fax? Are there shared folders? Where is the original install media? Does it have a static or dynamic address?

Bottom line is, an outsider (assuming all random outsiders are also IT technicians) should be able to walk in off the street and know, at a glance, every practical nuance of the device in question. Because frankly, that random outsider could be you. Sometimes a server could be a champ and work without any intervention for ages, and then POOF. It breaks, and you know nothing about it because you never had to.

Avoid the proverbial egg on your face with comprehensive documentation.

Software & Licenses

This can be a long list, depending on the size of the business in question. The types of clients I work with are comparatively small – anywhere from two to fifty users. But even small businesses typically have a surprisingly long list of software that they frequently use. If they use accounting software, one would hope that they keep a record of their correspondence with the vendor, which typically includes the key codes needed to activate the software. I would argue that any and all codes should be kept in a unified IT document as well.

The kinds of information captured here are purchase dates, license codes, license restrictions, registration information, system requirements or dependencies, and also vendor information.

My documentation will sometimes refer to to software user manuals, and I try to also identify where that manual can be found, to save time sleuthing around the internet.

Include Contact Info

Yours, the client’s, everyone’s. Include the phone company. The ISP. The web host. The domain registrar. The go-to electrician. Anyone who either you or the client might need to contact. It’s not enough that the info is on your speed dial. That doesn’t do the client any good after you were hit by a bus.

Diagrams

Perhaps one of the biggest time savers. Some networks are simple: a router with many clients. Some are not. Cover your bases. The definitive diagram designer application for Windows is Microsoft Visio, and for Mac it’s Omnigraffle. There are other alternatives. Diagrams aren’t always limited to complex networks either. Maybe the client has clustered servers or a co-location. Or maybe they utilize server virtualization. Diagrams are always helpful. That’s why instruction manuals are usually full of them.

Time Is Money

You may be sensing a theme here. IT documentation should be designed to save time. As a reference document, it saves your precious time, and makes you look professional, and more importantly, proactive. If anything were to happen to you, it’s also a form of insurance for the client, because now at least some of your extensive knowledge can be recovered or shared. If you work for a company with many technicians, then all the better. Your fate is no longer tied with that one client. You can send the new guy, if he’s up for it.

Update It Regularly

Regularly is relative. In some cases, collecting all of this information is done passively over a very long period. The last one I finished took roughly six months. The important thing is that you update it as you make changes, and audit it say once a year.

IT infrastructure is a living breathing beast that grows and expands with the business. Documentation should grow and expand with it, or it quickly becomes useless.

Use A Template

Save yourself time in the future by making a template in whatever word processor you chose. The information you collect is largely the same no matter who you’re doing it for.

Up until recently I used a Pages template (yes, on a Mac), because hey, it’s pretty. But now I use Scrivener, which is what you might call a document project management tool. At it’s heart, it’s a word processor, but with a few new tricks. How to use Scrivener is way outside the scope of this document, but suffice it to say, it’s perfect for technical writing. And for those of you who already use Scrivener, I’ve included a template that you’re welcome to use.

Scrivener IT Documentation Template

I was inspired to do this post by Sharon Bennett (@bennettbusiness) with her article “My IT Guy was Hit by a Bus!“, which resonated with me because my early mentors used the same metaphor to drive home the importance of – yes – documentation. Her post included a great example template that looks to have been written in MS Word, which I’ve included a link to as well.

Sharon Bennett’s Great Documentation Example

Her articles are actually really presented well and when I read them, I find myself nodding in agreement. She does a far better job at speaking to the Small Business audience than I ever have. Check out her site here: http://bennettbusinessconnections.com

Do you have any experiences where proper documentation saved you from disaster? Have your own templates or methods for documentation? Something important that I missed? Let me know in the comments!