Planung - Start IT Dokumentation Projekt

“How should I start my IT documentation?”
“What things should I document?”

We hear this questions a lot.

The answer: Ask yourself what documentation you need and reduce it to this needs. This sounds easy in theory. But it is hard in practice. 

Why is that? Because you tend to document too much and sometimes the wrong things.

Documentation wakes the hunter-gatherer in the system administrator. You might end up collecting stuff that you write into your documentation but never use. This guide should help you ask the right questions and find your way to your IT documentation. It does not raise the claim to give you complete coverage about the way IT documentation works – but it should be enough for you to set your goals and get started.

IT documentation
Some fundamental thoughts first

Dashboard i-doit IT Dokumentation und CMDB

The number one reason for a dying IT documentation is when you lose your trust in the accuracy of the documentation. This happens either when you find old/incomplete information or when you don’t have any trust in the documentation in the first place.

IT documentation starts with politics

Saying politics is – maybe – a little bit exaggerated. The goal is: You want your IT documentation to be accepted and used in daily business. How can you achieve that goal? Involve your coworkers and boss as early as possible. Try to not only cover your, but also their needs.

IT documentation needs to be consistent and central

This is the most important mantra to always repeat when writing your documentation.

1. Define a level of information depth.
When you document one piece of information for a single item (e.g. an IP-address of a server), you should document it for all other items as well (all IP-addresses of all servers).

What happens if you don’t? Documentation isn’t just for you, it’s for all the people you are working with. People rely on the information and expect it to be complete. If your coworker finds the IP-address of server A in the documentation, he expects the IP-address of server B also to be documented. If it’s not, he loses trust in the documentation (see “IT documentation starts with politics”). Set yourself small goals and try to reach them step-by-step. Yes, it is enough to just document the IP-address and hostname of all servers as a first step – as long as you cover all servers completely.

2. Documentation needs to be up-to-date.
If you don’t update the IP-address of a server in the documentation, the same thing applies as in point A: Your coworker finds out it’s the wrong IP and loses trust.

3. Documentation has to follow guidelines.
If you describe your printers as “HP Printer X” and the helpdesk guy documents them as “Hewlett-Packard printer X”, you will have a hard time reporting data about your printers. Set some rules for naming schemes!

4. Documentation needs to be placed in one central place.
Documentation comes in different shapes and sizes and if your platform can’t handle some files or graphics, just link it. You don’t need .ISO backup files in your Wiki, but you need a link to the place where these files can be found.

IT documentation needs to fit your needs

Don’t fall for the hunter-gatherer trap! Try to consider what your needs are in the daily business, what questions you want to have answered and define a set of information that you need. Set this information as a baseline that is known not only by you but also your coworkers.

If you document too much, you will never be able to keep the data up-to-date. Another drawback from collecting too much information is that important information might get lost within useless information, and you simply don’t find the information you want.

IT documentation needs to be planned and organized

There are two things to consider:

1. Documentation takes time.
So plan the time needed ahead and make this fact accepted in all your coworkers and bosses minds. There should be no arguing about extra time needed for documentation.

2. Include your documentation in your processes and projects.
There is a guide on how to set up new servers? Include the necessary documentation as a must do. New Exchange servers are being set up by third-party consultants? Inform them how to include these in your IT documentation. Let them know the exact requirements you have.

Technical and Operational documentation

These two belong together. Have one place where you document both kind of information. Technical information is the minimum. But you should also document why and how something was installed.

Keep these information asset- and/or service-centric. If you are looking at an E-Mail server, do not explain the MX DNS records in the E-Mail server context, explain it in the DNS server context. If configuration information like this is connected, have an additional service documentation that explains how and why these configurations belong together.

But now: roll up your sleeves and get busy

Let’s get the hands on the practical side. We start with different aspects that your IT documentation can cover. After reading about the different parts below, you should be able to decide which aspects should be covered in your IT documentation or not.

IT documentation step 1 : infrastructure

Physical Infrastructure

There is only one reason not to document your physical infrastructure: you don’t have any. It’s mostly very statical (so you only need to do it once) and in many situations you need to know where things physically are.

The level of detail is up to you. If you have a large datacenter you might want to document your IT-components down to the rack position. If you only have a small computer room, you just document the room the components are located at. Floorplans can come in handy when dealing with complex infrastructures.

IT documentation step 1 : networks

The Network

Network documentation is one of the most important things. You never should miss that out. It mostly consists of complex logical configurations that are hard to reproduce if systems are down and you don’t have a guide to it.
The good news: your IT documentation will be that guide.

Information to consider when documenting networks

  • The most important documents about your network should be network diagrams that show your LAN/WAN structures, routers, L2 and L3 networks. Split it up to multiple diagrams that show different views of your network, for example an office network diagram and a DMZ diagram.
  • Establish an IP address management
  • Document your DNS – You know the problem is always DNS!
  • Any routing information should not just be documented in the network diagram, but also in detail in text form
  • Information about switch ports and which devices are connected is a good idea to have at a central place. There are lots of ways and tools to get this information automatically.

The right time
to start your project is now.

Try i-doit free of charge for 30 days.

A word on firewalls

Firewalls get a dedicated paragraph here because I see too many people writing down too much information about firewalls. Yes, do document the basic information as defined for active components, but please do not document the firewall rules. I know, there is always a case where someone needs an exempt, but my suggestion is to have a copy of the rules (screenshot, config backup, etc.) in your documentation. Do not copy the data manually, it simply changes too often.

Security documentation is a whole other topic and discipline than your IT documentation, so do not try to cover the security stuff too much in your IT documentation. If you are interested in security documentation, take a look at ISMS (Information Security Management System) and Standards like ISO27001.

And what about the cabling?

We can hear your thoughts. “Really? The Cabling?”

Documenting cabling is a lot of work to do. You should ask yourself if it’s worth it. We all know it’s annoying to find out to which switch a cable is connected to and which server it runs to. But documenting each(!) single cable and wiring routes is a lot more effort to take. Remember: documentation needs to be consistent.

When does it make sense for your documentation?

  • You are in the cable business
  • You have a messed up cabling situation
  • You are working on the cabling with many different people
  • You have lots of wiring or a large/complex physical infrastructure
  • You start your cabling from the scratch

Administrative information

We can not stress this one enough. Administrative information are one of the most important things to document. Whenever your production firewall fails, you do not need to know what serial number the SSD has, but you need to know if there is still warranty on the hardware or if you have a valid support contract. And you need to know whom to call.

Information to consider when documenting:

  • Support contracts
  • Contact persons/companies/vendors (including addresses, telephone)
  • Accounting information
  • Software Licensing
IT documentation step 1 : servers

Active components

All active components – like e.g. servers, switches, routers – of your IT-infrastructure should be documented in some kind of way. Set yourself rules for what information should be documented about what kind of hardware. As stated before: set your own goals of which active components should be documented, if it needs to include e.g. mobile phones etc.

Information to consider when documenting active components

  • Basics (Name, Location, Serial number)
  • The IT-service it belongs to/purpose of the device
  • Physical location
  • Hardware (Vendor/Model and Hardware Information)
  • Networking (IP-addresses, Subnets, Ports, VLAN, DNS, etc.)
  • Operating System (Type, Version)
  • Installed Software
  • Installed Server roles and services
  • Specific Configuration settings
  • Accounts and passwords
  • Access (URLs)
  • Backup Up (How?/Where?/Cycle?)
  • Contact persons (and responsibilities)
  • Accounting information
  • Warranty information / Support contracts

Virtual Server Environments

To make a long story short: for virtual servers the same rules apply as for active network components. 

The only difference is: If you have a cluster of virtual hosts, don’t try to copy the exact configuration into your documentation manually. If you have an automatic process that updates your documentation about what VM is running on which host – that’s perfectly fine, but do not try to do this manually. Things change too often and you will end up with an inaccurate documentation.

Information to consider when documenting:

  • The same as for Servers/Switches/Router
  • Which VM is running on which Host/Cluster
  • Virtual Switch configuration

Storage Area Networks

You definitely should document your Storage networks, but only to a level where the data is still manageable and useful for you. In most cases, you need information about which LUNs are accessed by which servers. Some people want information about the FC cabling, some people want detailed information about the physical arrays and harddisks. Most people don’t. But that’s your choice.

Information to consider when documenting storage area networks

  • Basics (Name, Location, Serial number)
  • Hardware (Vendor/Model and Hardware Information, HDDs and physical arrays)
  • Networking (IP-addresses, Subnets, Ports, VLAN, DNS, …)
  • Operating System (Type, Version, License)
  • LUNs and what accesses them
  • Contact persons
  • Accounting information
  • Warranty information / Support contracts

Datacenter/Server room equipment

Any other passive equipment in your datacenter is mostly optional to document. Except the location there is no real guideline on what your documentation should include. One thing we often see documented about passive components is maintenance schedule and maintenance results.

A minimum that we would recommend is documenting the racks. Here is some other stuff that could be useful to have in your documentation:

  • Racks
  • Cooling Equipment
  • Fire Alarm System
  • UPS, Power supply in general 

If you are in the datacenter business or just have a large DC, you might want to take a look at a dedicated DCIM (Datacenter Infrastructure Management) solution.

IT documentation step 1 : clients

Workplaces and Client systems

This one is easy, but work intensive. If you are the one to keep track of end-user workplaces: document them.

Include anything in your documentation that you are responsible for, such as:

  • Client PCs
  • Laptops
  • Docking Stations
  • Monitors
  • Printers
  • Telephones
  • Mobile Phones

The documentation should contain at least the name, model, location, contact person and serial number of a component. The situation here is very different in every IT environment. It depends on what you as an administrator are responsible for – from support to purchasing new components.

IT documentation step 1 : software

Software & Licenses

The tricky thing about software documentation is the sheer mass of information. When you discover software with a tool, you get millions of unwanted information, such as all the Adobe Reader versions installed on X machines or driver packages.

Ask yourself what you (really) need:

  • Information about licensing?
  • Information about installed software versions (for security reasons etc.)?
  • Information about what software is installed on which server/client?

Depending on your needs, you should choose a strategy that can range from manually documenting software (which is okay when you just need the number of Microsoft Office Licenses on your workstations) to a fully automatic discovering of the software installed on every machine in the network. In most cases, it’s the best idea to get rid of useless information such as the driver packages mentioned above. 

Remember: storing too many information can prevent you from finding the information you need!

The right time
to start your project is now.

Try i-doit free of charge for 30 days.

IT documentation step 1 : it services

IT-Services

Now let’s have a look at the master discipline for the true Jedi among admins. Which components are working together? Which components does the Mail Service depend on? This is probably the most important set of information at all. Documenting your IT-services should be the final goal of all your effort.

But why is the documentation of IT services so demanding?

  1. It relies on all the other information that we talked about. The documentation must be there first.
  2. You do not only need to have an exact understanding of how things work together, but you also have to be able to write this down in a way that is easily understandable for others.
  3. Service components often change and you have to find an easy way to keep the data up-to-date.

There’s a lot more to say about documenting IT services. Hint: CMDB and ITSM.
But here is the minimum you should do, if you don’t want to deal with all the theoretical stuff:

  • Write down the services you deliver to your users/customers on a high level (e.g. “E-Mail”, “Webshop”)
  • Try to find out which servers and technical services are responsible for delivering the service. Write these down and reference the documentation for the individual servers/services
  • Document in which ways the service can be accessed
  • Document how you can easily test the main functions of the service, for example a login to a website
  • Write down any user or user group (including contact data) that the service is delivered to and include SLA information if there is any
  • Identify technical and functional contact persons for the service and document them

…and finally some words about Network Discovery tools

There are lots of useful Network Discovery tools out there. They can play a big role collecting vital information about your IT infrastructure. But always be cautious and don’t confuse them with your IT documentation. They can deliver an important technical part of what should be in your IT documentation, but they also deliver a little bit too much information for your daily needs. You rarely need to know the graphics card model in a server. Plus they are missing out important  administrative information such as maintenance contracts, telephone numbers, etc..

Your IT documentation should ideally be a combination of both, manually entered data and automatically discovered data. And if it’s possible, try to reduce the discovered data to the minimum of information that you really need.

The six steps to IT documentation

This is of course a lot of information at once. If you still don’t know how to start with your documentation project, we recommend our video series “6 steps to IT documentation”.

In six individual chapters we guide you through the project start with i-doit. You will learn how to start with the documentation of the infrastructure. Then you will document networks and servers. In the next steps you will add clients to your documentation. Finally, you will learn how to record software and licenses in a meaningful way. In the last step we will show you how to document IT services with i-doit.

In 6 Schritten zur IT-Dokumentation - Teil 6: Business-Services und Applikationen

Part 1
Infrastructure

In 6 Schritten zur IT-Dokumentation - Teil 2: Netzwerke

Part 2
Networks

In 6 Schritten zur IT-Dokumentation - Teil 3: Server

Part 3
Servers

In 6 Schritten zur IT-Dokumentation - Teil 4: Clients

Part 4
Clients

In 6 Schritten zur IT-Dokumentation - Teil 5: Software und Lizenzen

Part 5
Software & Licenses

In 6 Schritten zur IT-Dokumentation - Teil 6: Business-Services und Applikationen

Part 6
Applications & Services

Take a look at our video series. We look forward to receiving your feedback. 
If you have any questions regarding your project or i-doit, please do not hesitate to contact us at help@i-doit.com.

YouTube Logo

Subscribe to our YouTube channel