Why It’s Important to Create a Library of Network Documentation

I’ve always been a strong advocate of documentation, because in my very first programming project, I got a profound lesson on why no project or assignment was complete until descriptive written information accompanied the work product. I was a graduate assistant in a business Master’s Degree program, and the associate dean offered me a summer project to rewrite their Master of Business Administration student records system, a great opportunity I couldn’t pass up. The student who’d written the system had graduated several years earlier, and over time, problems with one function after another arose, making many parts dysfunctional with no support or other assistance.

I had less than nothing to start with, including a programming language I’d never heard of, PL/I. There were no program listings, nor any source code comments. No one knew how to compile a program, and no one in IT knew anything about PL/I, a relatively new product. No written documentation existed, no object descriptions were to be found nor its purpose (grades, credits, etc.), how objects interacted, usage frequency, initiation and termination. You get the drift. I found a book on PL/I in the bookstore (I still have it) and figured out how to compile; from that I got program listings. I was on my way to one of the greatest learning experiences of my life, and it wasn’t easy.

Documenting a Network

Documentation isn’t only important for programming; it’s vital for all of IT, including networks. It’s an unpopular task because organizations are action-oriented and objective-driven, including network management. In the short-term, this mindset makes sense, but in the long-term there’s a high price to be paid. Rewriting that student records system took a lot longer because it was a complete restart. Not only did programs have to be re-worked, so did every aspect of the application. Similarly, a network that doesn’t track performance, errors, availability and resolutions is condemned to repeat them over and over, at the expense of availability, response time and staff productivity.

Good documentation can dramatically improve network effectiveness and responsiveness, network administration and support, turnaround on equipment requests, acceleration of problem identification and resolution, streamlining inventory management and enhancing skills via improved training. Various network management functions are enhanced by establishing a comprehensive and interactive documentation methodology, including:

• Problem investigation and resolution
• Change management and scheduling
• Performance monitoring and tuning
• Network design and expansion
• Network technology and development
• Project planning and execution
• Staff and end-user training
• Historical research and analysis

Types of Documentation

The following are examples of documentation often used in network management departments:

• Network documentation policy statement. This defines the department’s mission and strategy regarding documentation, what documents or forms exist, and how to use, file, archive, etc.
• Network topology diagram(s). Geographical, pictorial, or graphical depiction of the physical network.
• Hardware inventory. Itemization of network equipment by type, location, maintenance level, vendor, server names, IP address, etc.
• Wiring schematics. Pictorial representation of cabling and wiring within premises.
• Software inventory. Itemization of network, laptop/desktop computers, cellphones, location, maintenance level, vendor, IP address, etc.
• Contact list/organizational chart. Staff roles and responsibilities, phone number, email address, availability, etc.
• Network procedures. Standard procedures used in network or network device operation.
• Trouble tickets and problem logs. Reports on problem resolution, maintenance, installation, user assistance, etc.
• Change logs. A chronicle of changes made to the network and associated devices.
• Performance data collection and storage. Data collected during a network’s normal operation; reports can be stored and archived, providing network performance history.
• Backup procedures. Steps to backup network components including restart and recovery.
• End-user agreements. Negotiated mediations on network responsibilities and related items like response time.

Documentation varies by organization, business type, network configurations, technologies, infrastructure, etc.

Network Documentation Needs to be Online and Interactive

Filling out forms or typing reports isn’t really an option, given today’s technology of laptops, notepads, cellphones, etc., and most network technicians simply don’t have time to key all details in resolving a problem, educating a user, installing a device or other tasks necessary to keep a network fully operational and functionally rich. Conversely, extensive documentation is crucial to a successful, productive network. Basing a documentation system on a real-time, interactive platform that automates much transcribing enables strong documentation with minimal effort.

Information isn’t useful unless it’s easily accessible, and network staff are unlikely to produce consistent, thorough, and accurate reports unless data entry mechanisms are simple and easy to use. Today’s technology makes that possible, and training makes it efficacious. Document creation, modification, review and analysis should be a standard part of a network staffer’s job, something that’s expected and that staff are incented on, something that’s easily accessible and is considered a valuable resource.

Inputting can be simplified through forms design, either by a “fill-in-the-blanks” approach, whereby an inputter can use check-off boxes to specify some items of information, saving keystrokes and reducing the effort, while other fields of information like name or date can be automatically filled in. Other fields may be filled in from other sources like an inventory file, a network design database or other datastores containing network-related information. And, of course, a certain amount of descriptive information needs to be keyed in, but if the effort to build the problem or incident ticket is relatively minor, staff members usually comply enthusiastically.

Putting the Documentation to Work

As the store of network documentation grows, it becomes a treasure trove of procedural, diagnostic, design, performance, historical and predictive capability, but it’s of no value unless the data can be sorted, categorized, manipulated, structured and formatted to provide useful patterns, trends, matching incidents, alternatives, efficiencies and a plethora of other data interpretations. This requires data analysis tools to help massage the data into meaningful forms and to process data via such functions as search facilities, sorting mechanisms, summarization tools, reporting facilities and many other data manipulation techniques.

Documentation can Produce Data

The width and breadth of reports that can be generated from documentation–and can produce more documentation–is vast and varied, a topic that justifies an article in itself. Data can be gleaned from spreadsheets, tables, charts and similar forms that are often numerically-based, making data extraction straightforward. Technology has advanced such that text documents–even handwritten–can be sorted, scanned and interrogated for data to use in a wide variety of reports and analyses. While tabular and textual reports can be very useful, graphical, linear, pictorial, three-dimensional techniques and simulations can present information in ways much more enlightening, insightful and meaningful, providing both management and staff with new and more powerful tools to run their operation.

It Doesn’t Have to be Built from Scratch

Building comprehensive, powerful network documentation function can be an intimidating project that consumes extensive effort and can take months or years, but that doesn’t have to be the case. A variety of vendor products exist that reduce the effort of establishing a network documentation function, while simultaneously providing richer function than possible with a roll-your-own approach. These products are seasoned with the experience of many other network management departments, using code hardened and improved with other clients’ experience and every conceivable form of network. Time and research should be invested to find the right product, and implementation should involve the entire department, seasoned with education and interaction with users and industry conferences.

Documentation is Priceless

A well-thought-out, easy-to-use, flexible and informative documentation system is a tremendous asset to any business function, and because of a network’s importance to most enterprises, even more for network support. Documentation is one of the most powerful management tools available, because documentation is information, and information is not only powerful, it’s the guiding beacon to good decisions, the spotlight on problems, and the key to insightful solutions. When done right, documentation isn’t the tedious chore so many think it is; rather it’s the enabler of productivity, the creator of economy and one of the fundamental essentials to excellent performance.

---