How to produce good documentation – Part 1 – The foundation of any IT infrastructure

Oh No, that word….

Documentation is like a dirty word in a technicians mouth, we all hate producing it and we all hate keeping it up-to-date, but we all understand the value that it holds.

Some technicians despise keeping documentation, rather keeping it within their own heads, this is idea is built up from years of keeping themselves useful by being the only person in the office who can do X Y or Z.

But this is an old way of thinking, people are more tech savvy, and let’s be honest, Bosses, technical or not are more confident in today’s world that if they get rid of the said person, they’ll be able to replace them with some young kid who will pick up the pieces quickly and probably take the company in a new direction and produce better results.

So with that, I am going to outline some steps, tips and guide you on how to create documentation for your existing environment, or for a new project your under taking.

What is good documentation?

Everyone’s fear is a complete meltdown type disaster, you’ve lost everything.

You need to rebuild, where do you start?

Well as far as I’m concerned your documentation should allow you to rebuild your environment, i.e you can trash everything, start again and get back to the same point again.

Ok so we cannot capture absolutely everything, especially in an existing environment, but we can make a good hole in to it.

Headings

The easiest way to start is to get underway with your documentation is working off headings.

Lets look at Technologies first, after that the finer details of such (Active Directory, Replication Partners). We can then move onto company software at the end (AutoCAD, Sage).

If you have no documentation at all, its best to start with an overview of your infrastructure. There is no point diving straight into how your etherchannel links are configured to your VMware ESXi hosts.

Here is a link to a template based on the below.

So let’s have a look at some possible headings;

  • Infrastructure Overview

A summary of the infrastructure, such as. This document relates to the VMware VDI infrastructure used for client based access by students of the college internally and externally.

And then on to explain the top-level hardware in use, how its split across areas, what model is employed? (I.e for switching, Cisco’s Core, Distribution, Access)

  • Network Platforms
    • Switch Topology – Layer 2
    • Routing Topology – Layer 3

Mainly this would be diagrams of the topologies, and links to where copies of the configurations are held. And a separate document listing the IP addressing scheme, including devices with static IPs. Don’t forget Public IP addresses in use as well.

  • Physical Server Infrastructure
    • Server Room / CAB Layout

Another diagram of what is where in the Server Room and Comms room racks. Probably an appendix with some actual photos of the rooms as well.

  • Virtual Infrastructure
    • Cluster details
    • Virtual Hosts
    • Virtual Networking
    • Virtual Datastores
    • Virtual Disks (VMDK/VHD)
    • Virtual Snapshots
    • Virtual Guest Resources

Once again this is more of an overview, and a reference a separate document which goes into more detail about the systems.

  • Storage Platforms
    • SAN
    • NAS
  • Backup Provision & Disaster Recovery

Which software is used, which systems it backs up and to which location

  • Active Directory & Windows Server Environment
    • DCs / FMSO Roles / GCs / Sites
    • DHCP
    • DNS
    • Group Policy
    • Remote Access
    • Third Party Software / Line of Business Applications

Another subject which will more than likely require its own document.

  • Backup Provision & Disaster Recovery

This should reference any DR you have in place, and which document to see in regards to failing over to the DR.

  • Internet Connectivity / WAN
    • Firewalls
    • IPS
    • Proxy
    • Service Publishing

Some more diagrams needed, explaining traffic flow to the outside, etc. And a table listing the mappings of internal resources for access from the outside. (NATs and PATs).

  • Credentials & Access Requirements

A secure document or application should be used for the containment of passwords, but you can link to this option, and list things like security groups in AD used for access to things, I.E VMware vCenter access linked to an AD group.

Summary

This is not an exhaustive list of things you can detail, but should be enough to get you started on writing summaries of each, for example, what backup software you use, which servers it is located on, how to access this sever.

From here you can then link to further documents such as Service Operational Procedure Documents or SOPs, i.e How to restore a file from a tape backup.

In the next few posts we will be looking at how to populate these documents with the right kind of information, and creating diagrams which are meaningful rather than just something nice to look at.

Dean

Share

One thought on “How to produce good documentation – Part 1 – The foundation of any IT infrastructure

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.