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:
- A chassis (for slide-in units),
- a rack (in which chassis or servers are installed),
- a workstation (to which devices are connected),
- a room (containing racks or workstations),
- a floor (in which there are rooms),
- a building (in which there are multiple floors),
- a campus (in which there are buildings)
- a city (in which buildings or campuses are located),
- a state,
- a state.
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:
- Room plans. They help you to find your way around. With software help, pictures can be stored or plans from CAD programs can be used. Later, the admin will probably want to draw the exact locations of equipment, racks, but also WLAN coverage into the plans.
- Rack Management. The plan of a rack is often worth its weight in gold. Here, however, manual methods quickly reach the limits of maintainability, but there are certainly situations in which this very representation comes in handy.
- Facility Management. Not only rooms can be managed with the plans, but also workstations, users, telephone extensions – up to the inventory of table, chair and fire extinguisher. Initially, the main focus should certainly be on important IT components.
- Operational equipment. Fire extinguishers, UPS systems, power backup or air-conditioning systems all have one thing in common: an inspection sticker, often issued by the TÜV (German Technical Inspection Agency), which provides information on when the next inspection must take place. Partly insurance-related, partly legal or simply operational necessities are the background. Ideally, the documentation should automatically remind you of these dates, and a report on the inspections due in the following month facilitates work planning.
- Cabling management. It is often necessary to document cable connections. Especially when patching, this is a great help in answering the recurring question: Which strand can be unplugged?
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: