# Network documentation best practices for a topology that stays accurate Drawing a topology is the easy part. The real challenge is **keeping it accurate**. Documentation that no longer matches reality costs you time during an outage instead of helping. These best practices help you build network documentation that stays reliable, whether you work in NetPlottr or another tool. ## Document with a purpose First ask yourself who this map is for and what it is meant to do. The answer determines the level of detail. A management overview does not need port numbers, while an administrator resolving an outage needs exactly those details. Common goals: - **Troubleshooting**: quickly see which path traffic takes and where it can stall. - **Onboarding**: help a new colleague understand how the landscape fits together. - **Audit and compliance**: demonstrate how segmentation and access are arranged. - **Planning changes**: assess the impact of a change in advance. :::tip title="Several focused maps work better" Prefer several focused maps over one map that tries to be everything. An overview map plus separate detail maps reads better than one unreadable whole. ::: ## Use fixed naming conventions Consistent names are the backbone of usable documentation. Agree on a convention and stick to it, for example a fixed structure of function, location and sequence number. The name `fw-ams-01` tells you at a glance that it is the first firewall in Amsterdam. Write the convention down somewhere too, so everyone follows the same rules. ## Build in layers Networks are too complex for a single flat picture. So work with layers or multiple maps: - A **physical layer** with equipment, locations and cabling. - A **logical layer** with subnets, VLANs and routing. - Optionally a **service layer** that shows which applications run over which paths. By keeping layers separate, every map stays readable and you can zoom in on exactly what you need. ## Capture the right details, not every detail More information is not always better. Documentation overflowing with detail ages faster and gets read less. Focus on what is stable and valuable: - Which component serves what purpose and who owns it. - How segments are separated from one another. - The critical paths that a lot depends on. Data that changes often, such as temporary IP assignments, is better pulled from an automated source than maintained by hand. :::info title="Rule of thumb for what to capture" Document by hand what rarely changes and needs context, and leave fast-changing data to systems that keep it up to date automatically. ::: ## Make updating part of your process The most important rule: a map is only finished once updating it is guaranteed. An outdated overview is more dangerous than no overview, because people rely on it. So tie updates to your change process, so that a change in the network automatically leads to a change in the documentation. Agree on who is responsible and check periodically whether the map is still accurate. :::howto title="How to keep your topology current" 1. Agree on a **naming convention** and record it centrally, for example `function-location-sequence`. 2. Start with a rough map of the **core** and then add detail layer by layer. 3. Tie updating to your **change process**: no change without an updated map. 4. Assign an **owner** who is responsible for the documentation. 5. Schedule a **periodic review**, for example each quarter, to check whether the map is still accurate. ::: ## Store and share securely Network documentation is a detailed description of your infrastructure and therefore sensitive information. A few principles: - Grant access only to people who need it. - Store maps and exports in a protected, managed place, not as a loose file in some random folder. - Be careful about sharing exports outside your organisation, for example with vendors. :::warn title="Treat a network map as confidential" The information that makes your management easier also makes it easier for an attacker who stumbles upon it. Limit access and keep exports inside your organisation. ::: ## Start today, not someday The best documentation is the documentation that exists. Start with a rough map of the core and refine it over time. Not started yet? Our guide [[netplotter-aan-de-slag|Getting started with NetPlottr]] helps you on your way with your first topology. :::faq ### How often should I update my network documentation? Preferably right at every change in the network, tied to your change process. In addition, schedule a periodic review, for example each quarter, to check whether the map is still accurate. ### Should I put everything on one map or make multiple maps? Several focused maps almost always work better. An overview map plus separate detail maps per layer or location stays readable, whereas one map that shows everything quickly becomes cluttered. ### Which details are better not maintained by hand? Fast-changing data such as temporary IP assignments. Pull those from an automated source instead, so your documentation does not age immediately. ### Is an outdated map really worse than no map? Often yes, because people rely on it during an outage. A wrong overview sends you in the wrong direction, whereas with no map you at least know you have to figure it out yourself. ### How do I store network documentation securely? Limit access to people who really need it, store maps and exports in a protected and managed place, and be reserved about sharing exports outside your organisation. :::