Categories: System Admin

Best practices for documentation- The sure-fire way to get the job done

At some point, every admin will need to create IT documentation. Here I demonstrate how to succeed in doing so with these simple steps.

First, how should you start documentation? Mountains of complexity are already threatening to pile up. It should also be done quickly, because the admin has already been dragging the task around with him for some time. And, please, it should only be a one-time effort.

Can there be a patent remedy for this? Isn’t every company, every IT department different and needs individual guidelines for scope and level of detail? After all, a data center operator is subject to different regulations than a user in the public sector. The admin of a medium-sized company certainly has different concerns than those of a cloud provider.

Despite all this, there is a logical sequence to documenting where the steps build on each other and do not repeat. It is this sequence of steps that this and the next articles in the Best Practices series aim to present. Even if one of the points listed here is not on your agenda, you should at least try out the method presented here as part of a pilot project.

Step 1: Document infrastructure

Anyone who has to manage several sites or even just rooms knows the plight: Where is …? Where something is located is a key question for most users of documentation. The location also plays an important role for all subsequent documentation tasks. Therefore, it is wise to define it from the beginning. This information is relatively static; changes are rare. The time for this step is therefore well invested.

Anyone who undertakes documentation should therefore take the next inventory as an opportunity to compile an up-to-date site overview. The admin will document many things for the first and last time, I promise! The principle is: Each location is documented only once. Locations in this sense can be:

Not all levels are always needed, of course. Since no element is duplicated, the one-time documentation may take a little more effort: In addition to the name, it is recommended to record other properties: the exact address, the contact persons (for access or alerting), a telephone number of the extension in the computer room, and so on. Those who document, remember that in the worst case, people who have never been to the premises will have to find their way around!

How should the person in charge deal with missing information? Many documentation projects have starting problems: There is no clear designation of rooms, no room numbers. Therefore, supposedly, it is not possible to proceed with the documentation of the locations. The project seems to be stuck from the beginning, but you can’t wait for a number assignment sometime later!

In case of doubt, it is better to invent a nomenclature, because the serious case does not wait for the room number project either. The admin can use aliases instead and write a speaking explanation in a remark field (“Second room to the right of elevator on the second floor, room number unclear”). In server rooms, a label can be placed on the inside of the door, should that be prohibited on the outside: “You are in room with IT internal designation # r1105.”

Communication is everything

The labeling of documented objects should always be unambiguous. Those who have chosen a database as the platform for their future IT documentation usually do not have to worry about this – in this case, the database already enforces unambiguity. However, if Excel, Wiki, Word and Visio are the tools of choice, it is up to the documenter to assign a unique ID: An enterprise-wide unique sequence number is not only useful, but necessary.

We are not talking about the serial number of a device or host names here; in practice, these features occur twice, intentionally or not. Even duplicate MAC addresses are possible thanks to virtualization. So the admin has to come up with his own system of ID assignment. If chosen wisely, this also makes later import into a database system much easier.

You can already do a lot with the documented locations:

Whether or organization is large or small, documenting these basic things is essential for keeping the show running.

As an add-on, here’s a great video on the topic of documentation best practices:

Article info



Leave a Reply

Your email address will not be published. Required fields are marked *