How to produce good documentation – Part 3 – Network IP’s & Interfaces

The time is here, lets look at starting to document that network of yours.

Now lets look at the other side of the coin.

Click the above for the templates used in this diagram

SwitchPort Diagrams/Tables

So it’s not all creative visio diagrams, one of the best pieces of documentation I find that I produce is actually a switchport diagram.

Using Excel to diagram out a given number of switches, mapping the interfaces to the hosts or devices in which is connected to them.

By colour coding the cells,

  • Each interface number linked to a VLAN
  • Each connected device has its own assigned colour.
Switchport Diagram Example

So lets look at this in action, or on paper (virtual paper).


So nice and simple,

  • Name of the Switch
  • Physically Identifying which switch in the stack
    • You could use the member number, or slot number if it is a chassis
  • The interface numbers (I usually find 24 ports per line is best)
  • The name of the device connected to the interface
    • Also identifying which physical NIC on the device

At the bottom of the table, I have my Legend, so to speak, where additional information about the connections may be held.


So we can identify VLANs via colour, used along the top where the interface number is. We have a colour used for where an interface has multiple VLANs trunked.

The devices also have their own colour as well, included as well for reference is which HP Switch trunk interfaces are mapped to the devices aswell.

Finally, I include a basic representation of the devices physical NIC layout, the identifying number used, and which Switch/Slot it is plugged into.

So in the first screenshot, we can see that EDUC-ESX1-ETH1 is plugged into Top Core Switch port 1.

Looking at the below, we can see which port if we were looking at the physical rear of the device, is port 1, with colours used to represent the VLAN’s once again. By doing this for each device, we can see quickly and clearly, which VLAN a particular NIC is in, and that is balanced evenly against the switches/slots. Showing if one switch fails, the device will remain operational due to the redundancy.

This is particularly helpful for the SAN device, where we can see that we can tolerate a failure of a switch, and still have an active SAN, or a failure of a controller, and still have an active SAN.


IP Address Scheme

This can be added to the above document on additional tabs, or as a separate document. Understanding the IP address schemes in use within a company can go a long way in being able to quickly identify devices currently on the network, and available spaces for new devices to be implemented.

So what do we need to think about?

  • Global Scheme
    • Overview of each site
  • Public IP address
    • What ports are used
    • NAT to inside addresses/devices
  • DHCP Scopes
  • Static Mappings for DHCP Scopes/Sites etc
The Global Scheme Tab

So lets look at the Global Scheme headings we need and how we can include the Public IP address information with this;

  • Site/Location
  • Private IP Scheme
    • Network
    • Broadcast Address
    • Subnet Mask
    • Mask Bits
    • Available Host Addresses
    • Start/End Usable Addresses
    • Gateway Address
    • DHCP Range
  • Public IP Scheme
    • Public IP Assigned Network
    • Public IP Subnet Mask
    • Public IP Gateway
    • Public IP Start/End Useable Addresses
    • UN/PW needed, i.e for ASDL Line

And this is how it looks within a table


The Individual Address Range Tab

So here we can go into as much or as little detail as needed really.

If your Address Ranges for Servers to Clients are different, you can split the tabs up to reflect this.

For Clients, you can record the static IP information, with headings such as;

  • Device Type
  • Hostname
  • IP Address

For the Servers however you may want more detailed information which will cover headings such as;

  • Type of Server (Physical, Virtual)
  • Server Hostname
  • NIC Adapter (Name of NIC within the OS)
  • IP Address
  • Subnet Mask
  • Gateway Address
  • DNS Servers Set
  • Public IP Address
  • Remote Console IP (iLO IP or iDrac, etc)

You can also include additional headings where you can simple mark it as true or false with an “X”, such as;

  • AV
  • Internet Access

Marking, if installed or available.

And here’s a quick example;



By capturing this information, you can quickly build up and idea of your network from a physical point of view, where by you can easily spot configuration mistakes, such as ports in the wrong VLAN, or servers that have the wrong DNS settings set.

Using the switchport diagram, you can target particular devices, and ensure that your network cabling requirements have been achieved, when installing VMware Hosts, my main goal is to ensure that the physical server NICs are split across multiple switches in a way that the host can carry on working without affecting the VM’s should a switch fail.

From a technical perspective this can be worked out by looking at the device names against the switchport number, however from a high level view, including something similar to the 3rd screenshot, where by you represent the Physical layout, you can demonstrate how the ports are linked to the switches. In the future, should another host node be added to the environment, if it is a different engineer carrying out the work, they should be able to follow this design and install a device in with the same networking redundancy.

For the IP Address scheme, you may be able to pull some of this information using powershell, but to get yourself started, I would use a tool such as Angry IP Scanner, find all the active IP addresses on your LAN, then record them and start to build a picture of your network.

Having the addressing scheme available can quickly show you how wide a particular scope is, if your Wifi VLAN can support 253 hosts, and you purchase 500 new laptops, you know quickly that you need to expand that VLAN. Having the table there means you can then work out the correct changes needed.

In Part 4, we will tackle how to visio diagram your network device connectivity, looking at one of my real world paper diagrams, and how I converted that into a visio document.





8 thoughts on “How to produce good documentation – Part 3 – Network IP’s & Interfaces

  1. Hi Dean.

    first of all thanks for nice series about documentation.

    I’m big protagonist of documentation and I’m continuously trying influence my customers to do projects in three phases – Plan, Design, Implement (aka PDI). Planning and Designing is the phase where the most of the documentation should be done because nobody will do the great documentation after implementation. Do you agree?

    So when we agree with PDI we should define how Plan & Design document should looks like. That’s where Conceptual, Logical and Physical parts of documentation come to play.

    Conceptual design collects all requirements (business and technical), constraints, and assumptions. It is often called Design Factors. Everything should be driven by these factors. During design phase you will identify risks associated with requirements, constraints, and assumptions. These risks must be documented and mitigation options identified. This is the risk management and some risks can be simply accepted. The biggest risk are undocumented and therefore hidden risks .

    The documentation have to be separated into conceptual. logical and physical parts.

    Conceptual part is good for overall view of the whole documented system. This is good part for business owners to understand the concept.

    Conceptual design must be decomposed into logical components and Logical Design for each component is going into deeper detail however without physical specification, product definition or details like IP addresses, port-channels, DNS entries, and so on. Physical design is the part where each logical component can have these details.

    Logical parts are good for subject matter experts for particular technology like compute, storage, network, management, monitoring, security, recover ability, etc…

    Physical parts is important for implementers and operational guys.

    It is not easy to create good documentation. Therefore I would like to thank you again for your blog post series and open this topic in public community.

    That’s my $0.02.

    1. Sorry its taken me a while to getting around to approving this comment, but yes I do see where you coming from. I guess documentation is always crucial, however its down the company policy on how its implemented. For me, I work for an IT solutions provider, So documentation is a key part of any project that we complete.

      Where as if you are working for the IT department of a private company, documentation usually comes second to firefighting.

      Im glad you’ve enjoyed my posts so far.


  2. I think network techs view documentation in different ways some find it a drag as it is indeed labour intensive to do well, while others view it as a good investment of time. I am of the latter opinion.

    Too many times have I joined network teams and found either a serious lack of documentation from how to’s to detailed diagrams that can aid trouble shooting. The problem comes when documentation overkill happens, docs are created without any thought to how they can be used to add value to the documentation store. Couple this with in-accurate naming and poor filing and it becomes just as bad as having no documentation as time can be wasted trawling through documentation that provides no relevant information.

    You detail some great points that aid network techs at all levels understand how issues can be impacting the environment and how they can be resolved. The key to ensuring that documentation is relevant and accurate is indeed in following David’s approach, however techs also need to be proactive outside of the project phase and documentation reviews are a good way of ensuring that your docs store stays up to date and relevant.

    Great posts Dean look forward to more of them, Cheers Steve

    1. Thank you for your feedback Steve,

      Yes the approach varies, but the goal should be some what common.

      I do plan on getting back on this series soon!

  3. Hi Dean, would you be happy to provide these (and part4) screenshots as templates? I think we could all benefit 🙂

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.