High Level Design / Low Level Design (HLD/LLD) ... also Architectural Handbook

[deanwebb]

I'm writing them again, which means I'm dealing with the definition of these things, again.

As concepts, they're pretty straightforward. HLD will show the overall placement of devices, criteria used for placing them, shows what the devices need to connect to, shows what devices will connect to it, and so forth. Once you've read it, you'll know that Berlin is a level 2 site, so it will have WAN routers in HA, but the pair will share the same pair of ISP connections... or something like that.

The LLD will show what TCP/UDP ports are used in connections, which wires connect to what switchports, logical and physical routing of the traffic, and will likely be site-specific. Once you've read the LLD, you'll know that the Berlin WAN routers use ports Gi0/0 and Gi0/1 for redundant connections to the core switches, ports Fa0/0 and Fa0/1 for HA and ports Fa0/2 and Fa0/3 for ISP connections... or something like that. The HLD is apparent to anyone that reads the LLD closely, but only for that site.

As deliverables, however, we have a range of opinions about what should be in them...

At one extreme, there's a school of thought that the LLD is a one-page Visio diagram, no more. The HLD is a brief bill of materials and set of specifications for the system to function. Neither explains precisely what the connections are used for, just that they exist and they're necessary.

At the other extreme, the thinking goes that the LLD is a Visio diagram with explicit information about each connection and what can and should be done with it. This document can run to over 100 pages, but it has ALL the information in it. To make it apply for another site, either include each site's specifics in the LLD, or make one for each site, using the handy search and replace function. The HLD is equally massive and will have a complete description of the system, possibly matching the vendor's admin guide in terms of scope and detail. It may or may not also include elements of the Architectural Handbook (AH), which itself is the highest-level of documents.

The AH should be there to describe the overall purpose and intent of the system and how it will address the needs of the customer. It is not a standalone document, but is meant to integrate with the other AHs to provide an overall view of how all the IT in the firm fits together. As with the LLD and HLD, there are thin extremes and there are thick extremes.

Whatever the size of the documents, the best case in any firm is if there are standards for them. If there is a template to follow for the AH, HLD, and LLD, you have a great situation. If there are no templates, or there are multiple, competing templates, you may face the possibility of having to re-write your documentation to fit another template once one is settled upon or, worse, a different template is temporarily ascendant. If templates rise and fall in and out of favor, you may be involved in re-writes every 9-18 months.

If you're lucky, you'll have a good tech writer assigned to a librarian role, who can assist in maintaining the documents as things develop. When you first write your design documents, you can't predict whether or not you'll have the same set of conditions over the years to come. Naming conventions change. Software vendors change. Hardware vendors change. With each change, the documentation needs to be updated. As I said, if you're lucky, that tech writer will get relevant technical details from you, the engineer or architect, and then incorporate the changes in the documents. You may have to book a meeting to flip through the pages and identify where changes are needed, but after that well-spent time, the docs will be the tech writer's task to complete, not yours.

If you do not yet have standards in your organization, make them. If another team has standards, follow them as closely as you can. If your firm is not all that big and nobody thought to standardize anything just yet, make your move now.

What standards should you choose? If anything, try to have your documentation so that it is able to stand the test of time. For example, if you have a naming convention, don't repeat it in your document. Reference the naming convention. That way, when the convention changes, your document is still OK. "Follow document "Current Network Device Naming Convention Standards.docx" for naming the switches. At the time of this writing (4 November 2017), an access switch in Berlin would be named EDEBESWACxxxx, where xxxx is a 4-digit number, starting at 0001 and incrementing by 1 for each additional switch... "

What are your thoughts on the AH, HLD, and LLD?

[deanwebb]

Massive gravedig on my part because I had a massive mess happen because someone said, "Write us an HLD" and what they got was what *I* thought was an HLD... but was not what *they* thought was an HLD...

If you don't get guidance in what your HLD needs to contain, then don't start writing it. Get that guidance ASAP and find out also if it's for a project milestone or a vendor requirement - is it something they need eventually or is it critical path?

[DesertFox]

Communication is king as always.

Anyhow - my understanding is that HLD - this is for the architect/engineer to know how the network was designed, what services are presented in the environment, etc. LLD - just the details that configuration engineers needs (if TS is not needed) - like ports / ip-s, physical ports (for the fields), etc. The guys that make the actual provisioning doesn't need to know that in the next DC there is a Domain Controller. But he should know what port numbers / ip-s to be allowed for communication with Domain controller- and this should be presented on the LLD.

P.S. In my last company we put the IP-s to the HLD  as well. But most of the times it was the only diagram, especially for smaller customers (with identical branches).

[icecream-guy]

in the bid process, the HLD is an 10000 ft overview that addresses the needs in the contract proposal
when one wins that contract, a LLD down to the wire/port and all that good stuff is needed to understand how deep a grave you just dug.

[deanwebb]

However, when an HLD is something that a third-party network management company wants to see before it does any implementation work with a new vendor, it's a massive volume with all kinds of LLD stuff squished in there. This is three times as true for European companies - there's already a tendency to over-document in most European companies, but this gets amplified mightily when they use a third-party network management company.

PROTIP: Ask for a sample HLD before you say, "Oh yeah, we can knock one out in 40 hours."