ISND

That's not a typo in the title. I mean ISND, the International Standard for Network Documentation. You should be familiar with it, but maybe you never heard of it?

This post is about documentation. Documentation can be a lot of things, there's IP documentation, Rack documentation, Network diagrams and so on. Here I'm going to focus on the diagrams, since they are the most common and often the worst kind of documentation.
When I say worst, what I mean is, they are the ones most network architects struggle to produce at a high quality. They are also the ones which are most confusing to read and not always very useful. When you're looking at a network for the first time, you are often thrilled, that someone actually did the documentation, but when you read it, it doesn't contain the information you are looking for or it isn't completely clear, so you end up going through the configuration of the equipment to find out, how it's put together.

Why is that? Why do we struggle to produce good diagrams and why do they rarely meet the needs of the people who read them? The answer is quite simple: There is no standard, there are no guidelines, there are no principles. That's why you never heard of ISND.
I spent a lot of time on Google trying to find something useful. It isn't there. The best I could find, was explanations of the importance of network diagrams and documentation, naming conventions and so on. There is a certain level of agreement on the iconography and that's it. I also never heard of anyone who had a good education on how to draw diagrams. This puzzles me, since it is one of our main tasks to produce good diagrams and read other peoples diagrams.

So I have decided to explain to you how to do good diagrams. Hopefully this will help you if you unsure about how to diagrams or give you some additional inspiration, if you do good diagrams already.
It's not really that difficult. Consider architects for a moment. They produce a lot of drawings. They produce design sketches for clients to look at and they produce technical drawings for the builders who construct the house. When clients look at the sketches they can visualize the new house and when the builders look at the technical drawings they now exactly what to build. They don't get a 10 page report describing how the house should be built, they only get drawings. The sketches can be show to any client, even you and me, and we can visualize the house. The same goes for the technical drawings. They are not specific to any builder. You can give the electrical drawing to any electrician, the plumbing drawings to any plumber and so on.
What you notice, is that there are specific drawings, based on what you want to look at. You can't give the electrical drawing to the plumber or the design sketch to the electrician. They all serve a specific purpose and contain only the information, that is relevant for that purpose. The design sketch has no measurements, nor does it show where the water pipes go.
This is where so many network architects go wrong in their diagrams. They try to cram all the information into one diagram, that will contain everything. This can't be done, you can't read it, it's unclear and you can never fit all information on to the same diagram, since some of it needs to be depicted in different ways.

In the next post I'll explain to you how to apply this knowledge to network diagrams.