20 Answers
20

It depends on the size of the network, number of users, number of nodes (computers, servers, printers, etc.) and the size of your IT staff, among other things.

It also depends on your goal. Are you documenting the network for training and maintenance purposes, insurance/loss prevention, etc?

Personally, I document my networks in such a way that I know I can derive any missing information based on what is documented. From a practical stance, there is a point of diminishing returns when your documentation gets too granular.

A good rule of thumb I use is that there should be documentation in a known location that is thorough enough that if I get hit by a bus tonight, another administrator can keep the core network running while he/she fills in the missing pieces over the next few days/weeks.

Here is an overview of what I think is most important about one of my networks. For the record this is a Windows-only shop with about 100 users and 5 offices.

Administrator credentials for all servers. Obviously this should be kept secure.

IP Addresses and NetBIOS names for any node on the network with a static IP address, including servers, workstations, printers, firewalls, routers, switches, etc.

Basic server hardware information, such as Service tags or equivalent, total disk capacity, total RAM, etc.

Major roles of each server, such as Domain Controller, File Server, Print Server, Terminal Server, etc.

Location of backup tapes/drives.

Information about the account numbers and credentials for services like remote office voice and data providers.

External DNS for websites and routing.

If there was anything strange about a setup or workflow that would not be immediately obvious to a new administrator, I would write a short "brief" about it as well.

Prose: A general overview in paragraph form, which helps with initial big picture and also can describe evolution over time

Tables: Tabular lists, either address-keyed, environment-keyed, or machine-keyed (preferably all of the above)

Diagrams: Definitely need diagrams with multiple levels of detail. On any decent size network, it's just impossible to sanely capture it all on one page and make it easily digestible. You want one diagram at the global level, with infrastructure devices (routers, switches, tunnel endpoints, etc.), and another several for the compute resources fronted by each of those routers or endpoints.

Additional notes about diagrams... Geographic distribution is an easy way to segment, but you also need logical views based on installation function. Also, label like crazy, making full use of typefaces and colors.

The most effective and thorough way to start this process is to build it from a disaster recovery scenario - e.g. the building went up in flames and all we have are the offsite backups. What will we need to buy first, and how will it need to be configured?

Kyle already gave great details, but I find that the DR approach helps me to take things one piece at a time.

Where I work - we faced the same problem when I first started here. As the number of servers and services increases, you find more and more out-of-date documentation, and with that comes the inevitable attitude for staff to not trust documentation, at least technical documentation on server names, server groups, networks, etc.

We started developing an open-source project called hotwire to address this...

By combining the inventory system with the build system, we've ensures that what is in the database is consistent with what's in our data centers, because we now have to enter the data into the inventory first in order to be able to build the servers.

A client program (funcwire) is then installed on all servers (as part of the build process) which then dynamically keeps an eye on the server hardware as reported by python-dmidecode, and what's in the inventory, so if anything changes, the admins will know immediately.

We've then integrated our wiki system so that each server, rack, project, hardware model etc in hotwire links directly to the appropriate wiki page.

We've hence "documented" our servers/network/etc using hotwire + a wiki (we use confluence here, but any decent wiki will do). (Note however that once the servers are built - hotwire does not modify them in any way - ongoing management is done via cfengine).

Generally you have a few different levels of detail similar to abstractions in software design documentation. You also document general device practices/procedures/configuration. Administrative passwords as applicable.

In an ideal situation, almost everything the next person may need is easily accessible and documented between your guideline and procedure documents + network layout diagrams.

The guideline and procedure documents should, in my opinion, be centralized wherever all of the IT docs are, and the network diagrams may have their own folder structure for multiple locations.

In the case of many satellite sites like a walmart/targer/home depot you would have a generic document for all the branch offices, and then some detailed whole corporation documents of main office interconnections and then you could dive down into office LAN documents.

Approach documenting a network as a developer approaches developing a system...

Consider the requirements - this has been well noted above, but consider WHO is going to consult the doc-o and for WHAT PURPOSE. Auditors will look for and read different artifacts than a peer SysAdmin.

Doing doc maintenance - many folks have mentioned the value of diagrams and maps, and as a visual thinker I heartily agree. BUT those things can be invalidated with a single act of adding/removing a host. Think about the 'right level' of doc-o - one that your group can actually maintain.

Date everything and include notes as to WHY you configured the network the way you did. Many, many folks forget to include a date - but the DATE provides a pointer into the history of the network. Invaluable for problem solving and it mitigates the inherent out-of-dateness of most network diagrams.

Offload documentation into "processes" - many times solid and well-crafted build/deployment procedures end up streamlining "network documentation" because the details of machine configuration and naming are better described in the procedures.

Key Takeaway: approach documentation as a 'system'; it must provide value from day 1 and it carries with it an inherent responsibility to maintain it.

Kyle Noland and other posters have covered a great deal on how to document. We are working on creating a standard web-based software(hosted internally by you) that makes it easier for network and system administrators to document their network.

We have following aspects covered in the software as of this writing(Apr 2012):

It usually isn't documented, but if you are being kind, you usually do it in a program like Visio or an open source equivalent. The most important information is what equipment is connected to what, and the passwords for any management console. The rest can usually be divined.

In my previous career as an IT Manager, my documentation binder included a Visio diagram of all the devices, a list of the IP address range allocations, all the product keys for Windows/Office/Acrobat, instructions on what needs to be installed on new computers with step-by-step instructions how, complete hardware inventory down to the component level, and last but not least the emergency phone number list: ISP tech support, router manufacturer tech support, etc.

Details of each server: standard stuff like serial number, amount of disk, ram, etc., but we also kept a running log of everything that was done to the box, starting with setup notes (o/s and app. install), then ll configuration and subsequent changes.

I never managed to do it completely, but I aimed to document all major routine processes - how servers were set up, how and what was monitored, account setup and removal, backup, etc.

Map and document your network may be a good way to transfer the necessary information. MS Visio is a diagram tool, but it is static and you have to spend a lot of time on it. I found NetBrain is an ideal network diagram tool to do this. It can document the network instantly and the documentation can be export to Visio or Word. I can customize the contents that I want while documenting my network. The customized contents include:


MS Visio is a good way to document a network, but it's not a free solution. Gliffy is a nice product if you're looking to keep your costs low.

Typical network diagrams show how information flows through your devices (and usually out to the Internet). So, you should have information in your diagram about where your computers, printers, WAPs, IP phones (if applicable), switches, and routers are located and how they are connected. IP addresses may also be included with the name of your device. This is helpful if you want to glance at your diagram for information on the fly.

As many have stated already, the network needs to be documented.
The problem I have seen is that network documentation is always important but usually not urgent. Many organizations have some sort of network documentation repository, but it is mostly out of date.

There are plenty of tools (some mentioned above), which can help you document the network, which one to choose will depend on the size of said network, but one thing I can tell you: the larger the network, the more automation you need, what you pay in the proper software you get back with interest in time saved doing stuff manually.