Introduction

We all know how daunting it can be to create and maintain documentation. Yet, when it is missing, we get frustrated. There is a standing joke regarding documentation:

Documentation is like sex. When it's good, it's very good. When it's bad, it's still better than nothing.

Nevertheless I believe we can all agree that documentation is a requirement for any system. Having good up to date documentation provides the following benefits:

• Give an overview of the system
  • Important if your employees leave, get sick, or are replaced. Gives the new employee or consultant (temp) a chance to learn the system quickly.
• Compliance
  • A reference for how the network should be build given the design choices we make.
• Audit
  • Many companies get yearly external audits. Most often documentation is a requirement for these audits.
• Troubleshooting
  • Software has errors. Getting help troubleshooting an issue is done much quicker with proper documentation.
• Provides the reasons why something is implemented the way it is.
  • Some designs might seem weird at first glance until you learn the reasons why it was made like this.

As with any document you create, it is a good idea to start by providing the reader a good introduction. Here the scene is set. Content suggestions:

• Which company is the document for?
• Which system is addressed?
• What can be expected of the document?

Basically ask: Why do we need this document?

Sensitive information must be scrubbed (masked) in the documentation. No passwords - not even hashed ones! Use a tag to replace a password, like this:

username <user> privilege 15 secret <password>
enable secret <password>

Any documentation should be written en English! The de facto language used in IT.

HLD

A HLD is a document that describes what a company wants for a system or network. It provides a birds eye view of what a company needs to get out of a system (design requirements). Examples of headlines/content of such a HLD:

• Introduction
  • Which issue/need does the design address?
• Drawings
  • Simplified overview of the systems building blocks and how they inter-connect
  • Logical representation of individual elements
• Company-specific parts
  • Buildings affected
  • Technology functionality requested
  • Restrictions
  • No clear-text protocols allowed (for example)

LLD

A LLD is sort of a follow-up document to the HLD. It shows exactly how the requirements of the HLD was achieved - technically. Here a rather deep dive into the chosen technologies and tweaks hereof are documented. It is detailed why and how the choices were made for the realization of the asked for solution of the HLD. Suggested content of a LLD:

• Drawings
  • Detailed versions of the drawing from the HLD. Remember to explain your drawings! What do they show? Why is this important?
• Naming convention
  • Hostname
  • Building names
  • Configuration naming
  • VNs/VRFs
  • VLANs
  • Interface descriptions
  • etc.
• Protocols
  • Explain why the protocol was chosen
  • Which tweaks were made (timers, optimizations, security)
  • Configuration example
• IP addressing
  • The structure, NOT the IP Plan itself!

Be sure to keep focus on the “why”. Justify your design choices. Make references to the HLD to show you listened to the business requirements and understood restrictions. Perhaps you were told that the staff has great experience with OSPF, hence you build the core IGP using OSPF rather than ISIS, because it would be too high a risk and too costly to teach the staff about ISIS. Or maybe it was decided that the cost was worthwhile and technical reasons lead to choosing ISIS over OSPF.

System documentation

This piece of documentation supplements the LLD. Also, this is where the administrator go to find information for daily operations. This documentation is updated and maintained frequently. System documentation includes:

• Drawings
  • A collection of the drawings from the HLD and LLD
• IP plan
  • Overview and detailed plan of IP allocations throughout the network.
  • An IPAM solution can hold this information
• Patch plan
  • Lists which devices inter-connect
  • Interfaces used
  • Optics
  • Cables
  • Important physical notes
• BoM
  • Bill of Material
  • List of equipment
  • Licenses
  • Service subscriptions
• Service contracts
• System owner/responsible
  • Technical
  • Non-technical
• Passwords
  • Password manager for safe storage of important credentials and service accounts.

User/Administrator/Configuration Documentation

Also known as user guides, administrator guides, or configuration guides. Could be based on an internal knowledge base with collection of how-to and FAQs. Systems used for keeping this documentation:

• Confluence
• Wiki
• Sharepoint

Maybe a user guide includes how to access a certain system and patch it. Or how to run a script. It could contain relevant system information such as scale numbers or links where this type of information could be found (data sheets).

Conclusion

Writing good and relevant documentation is a necessity when working with IT. We use it to remember, to understand, to collaborate, to troubleshoot, to educate, to validate, to benchmark… Without documentation we have no common ground for understanding the system. It makes life harder. Why not work smarter and document the work you do? Take professional pride in what you do by showing you care - document! And make it meaningful.

To sum up:

• HLD: What?
• LLD: How? Why? (of the HLD)
• System Doc: Operational documents (IP Plan, Patch Plan, Passwords, etc.)
• User/Admin/Confg Doc: Knowledge base, how-to, FAQ

Although we know that some poor documentation is still better than none, try to add value to it by including relevant information. I hope the above lists inspire you to write better and more useful documents!

Thanks for reading. As always, I’d be very happy to receive any feedback.