The Network

Network documentation is one of the most important things that you shouldn’t miss out. It mostly consists of complex logical configurations that are hard to reproduce if systems are down and you don’t have a guide (your documentation) to it.

Information to consider when documenting:

  • 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.
  • Do have an IP-address management. No matter if it’s a spreadsheet or a dedicated tool, just have one.
  • 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.

 

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.

 

Cabling

Really? Really???? 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. Either document all cables or none. (Except long Fibre-Channel or Uplink routes, you can also set your goals to see them as a set of information and limit your cabling documentation to “important” cables)

When does it make sense for your documentation?

  • You are in the cable business
  • When 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

 

Workplaces

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 detail of information should at least include the name, model, location, contact person and serial number of a component. The situation here is very different in any IT-environment, it depends on what tasks you as the administrator are responsible for, and these can range from supporting stuff to buying new components.

 

Administrative information

I 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-Services

The master discipline for the true Jedi Admins of the IT. 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 it is also the most complicated because:

  1. It relies on all the other information that we talked about (So 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 services, maybe I will cover this in another article. Use your Google-Fu to find out on what service documentation (Hint: CMDB and ITSM) is about.

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.

So 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.