guide to

documenting
networks

Dr. Diagrams

Note: All hyperlinks in this publication are

highlighted in yellow. For example, one
click will take you to the Contents page.

Document No. DD-3.0

Copyright 1998 by netViz Corp.
No part of this publication may be reproduced, stored in a retrieval
system or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior written permission of netViz Corp.
netViz is a trademark of netViz Corp. Other product names mentioned
in this manual may be trademarks or registered trademarks of their respective companies and are hereby acknowledged.

netViz Corporation
9210 Corporate Blvd., Suite 150
Rockville, MD 20850 U.S.A.
Telephone: (301) 258-5087
Fax:
(301) 258-5088
Web:
www.netviz.com

Contents
Getting acquainted 1

General strategies 3
A guiding philosophy 5
Getting started 7
Using standards 8
Managing a large documentation project 9

Basic design issues 15

Defining data fields 17
Naming data fields 18
Documenting workstations 19
Documenting cables 20
Documenting servers 21

Network documentation techniques 23

Documenting a LAN 25
Collecting data later 32
Showing port-to-port details 33
Documenting patch panels 40
Viewing logical networks and protocols 41
Combining physical and logical views 44
Taking advantage of SMS data 47
Linking to small nodes 50

Other techniques 51
Change control 53
Reassigning data to the key 56
Formatting text 58
Making floor plans 61
Keeping multiple legends in agreement 62
Improving bitmapped graphic appearance 63
Putting HTML output in frames 65
Reducing visual clutter from backgrounds 67
Forcing sort order in the Hierarchy Browser 68

Some final words 69

Critique your documentation 71
The end... or is it? 72

Getting acquainted

Getting acquainted
Question:

What? More stuff I have to read? Dont you people ever quit?

Answer:

I understand your concern. But its important for you to have all the information
you need to use netViz to its fullest extent. Let me explain three key resources
provided with netViz:

The netViz users guide describes commands, dialog windows, keyboard shortcuts and similar details. When you need to know exactly how to use any netViz
function, the users guide is the place to start.
Tip: Take the time to learn how to use netViz. A large percentage
of people seeking help from our customer service reps didnt
bother to read the users guide. You dont need to read it from
cover to coverbut you should be familiar with everything netViz
can do before you begin a serious documentation project.

The netViz on-line help is a condensed version of the users guide. It covers
the same topics, but leaves out the details. Once you are comfortable with
netViz, the on-line help is the quickest way to figure out any of netVizs many
features.
Tip: netVizs on-line help replicates the Mini-Manuals in Part 8
(Quick reference) of the users guide.

This book, Guide to documenting networks, contains practical advice on using

netViz to solve a variety of problems commonly encountered in diagramming
and documenting networks. Based on our own experiences and those of many
netViz users, the Guide is built around the general question of Whats the best
way to...?. Within that context, it covers a wide range of topics, from design
considerations to specific netViz techniques.

Question:

Now I see. But who the heck are you?

Answer:

Im Dr. Diagram. I have a Ph.D. in Theoretical and Applied Network Documentation Management Technology Studies from the prestigeous Eastern Tropical Paradise University of Southwestern Bimini. I joined netViz Corp. several years ago
and worked my way up the corporate ladder. Im currently Vice President of Answering Questions.
continued

Guide to documenting networks

Question:

Oh no. Does that mean this entire book is in question and answer format?

Answer:

Of course. Thats my job. After intense discussions, however, I reluctantly

agreed to keep the table of contents in traditional form.

Question:

Is that you on the cover?

Answer:

Pay no attention to the cartoon character

on the cover. This is what I really look like:

Question:

You know, I do seem to have a lot of questions about documentation. Maybe this
isnt such a bad idea after all. When can we start?

Answer:

Right away!

General strategies
Im finally gonna find out what that redand-yellow striped cable connects to.

General strategies

A guiding philosophy
Question:

Whats the best overall approach to documenting networks?

Answer:

Over the years, weve developed the following General Principles for creating excellent documentation:

Use consistent symbology. Rigorously define each symbol, line and color, and
assure they are uniformly applied. Good documentation leaves no room for interpretation. Your objective is to unambiguously transfer knowledge to those
who use your documentation. (See Using standards, later in this section.)

Use color to inform. Color can show static information, reveal dynamics and
enliven the view. Its overuse, however, can distract or produce disagreeable visual effects.

Use high resolution to achieve comprehensive content. Plan, organize and

structure your documentation to provide accessible, precise and useful information in a minimum space.
To clarify, add detail. (Edward Tufte, Envisioning Information)

Check for relevancy. Eliminate unnecessary layers, graphics and data.

Vigorous documentation is concise. A diagram should contain
no unnecessary objects, an object no unnecessary data, for the
same reason that a paragraph should have no unnecessary sentences and a machine no unnecessary parts... (a restatement of
William Strunk, Jr., The Elements of Style)

Eliminate duplicate information. Competent documentation tools can display

one piece of information in multiple places. This eliminates the need to manually synchronize nominally identical data replicates.

Maintain your documentation. Half-documentation is no documentation.

Maintenance requires discipline. Supplement with anything else that works, including utility programs and formal procedures. (See Change control in the
Other techniques section.)
continued

Guide to documenting networks

Use these principles to evaluate your design decisions and the documentation itself. If something in the documentation doesnt conform, discard itunless you
have a strong reason to do otherwise.
Tip: Post these principles where you can review them during your
documentation work.

Question:

Wow! Thats deep. So if I follow these principles, my documentation will turn

out great?

Answer:

Not necessarily. Theres a lot more to learn. The rest of this book will help you
put these principles into practice.

General strategies

Getting started
Question:

Documenting my network seems overwhelming. Where should I start?

Answer:

Understand your objectives. How will you use your documentation? Typical
uses include...
Troubleshooting and maintenance.
Help desk and user support.
Inventory and asset management.
Planning and design.
Some or all of the above.
Your objectives determine what data you need to collect and record. They also
suggest which data field should be the key (blue) field for different object
types. For example, if your objective is to support troubleshooting, you might
set up workstation object types with network address as the key field. On the
other hand, putting serial numbers in the key field works better for asset management purposes.
How you plan to use your documentation will also affect how you lay out your
primary diagrams. You could organize diagrams around physical configurations to emphasize equipment locations and cable runs (see Documenting a
LAN. Or you could prepare diagrams that highlight LAN technologies or protocols. (Selecting a graphical approach for primary diagrams doesnt eliminate
other options. Instructions later in Viewing logical networks and protocols
show how to pull alternate views out of the diagrams you already have.)

Start small. Break the task into smaller chunks that you can finish within a
few hours or at most one or two days. Then work onand completeone part
at a time.

Begin by documenting the most important components that directly address

your objectives. Here is one strategy that works well:
1. First, document components that support more than one user: hubs, routers,
switches and so on.
2. Next, document workstations.
3. Then document the cabling.

Documentation will become part of

your normal problem-solving process

Guide to documenting networks

Using standards
Question:

I can think of several different ways to diagram my network and record information about it. Is there some best way or standard way to do it?

Answer:

Networks vary widely in size, purpose, design and implementation. If there were
standard documentation methods, they would provide a reasonable framework.
However, no network documentation standards have emerged. Although you are
on your own here, these guidelines should keep you focused:

Establish internal standards so your documentation communicates clearly

and unambiguously to those who use it. Your own set of standard symbols will
allow someone to quickly scan a diagram and know what each symbol represents.

Be consistent. Use a given symbol to mean one thing and one thing only. Select certain symbols for workstations, others for hubs and still others for routers. Use thick blue lines for T1 links, for example, and thin black lines for
twisted pairs. Formalize definitions for colors: gray could represent equipment
out of service, while red indicates a critical condition.

Create one and only one netViz catalog. Base all netViz projects on this catalog. Besides enforcing standard symbology for all projects, this centralizes administration. When you add an object type to the catalog, it is then available in
all projects. When you change an object type in the catalog, the change is reflected in all projects.

Good documentation provides complete and accurate information quickly. Develop your standards to meet that goal.

Well-designed documentation helps

eliminate confrontations like this
8

General strategies

Managing a large documentation project

Question:

Youve obviously done this before. Maybe you can help me with another problem
Im wrestling with. My documentation project involves lots of people in different
departments scattered across a dozen facilities. Whats the best way to manage
this huge undertaking?

Answer:

There are several critical steps in creating and maintaining network documentation in a distributed environment:
1. Define your objectives. One person or a small group (depending on your organization) must clearly and concisely state the goals for the documentation. The
key is to determine what you want to do with the documentation: diagnose network problems, manage assets, plan for growth, recover from disasters, or
something else, or all of these.
When you have developed a mission statement, publish it. Make certain all
participants understand the objectives, agree with them and support the project.
This formal foundation is essential in assuring everyone will contribute to
(now) and maintain (later) the documentation.
2. Develop a comprehensive master catalog. This catalog will define object
types for all sites, devices (nodes) and interconnections (links), with their respective data structures. If you will be interfacing the documentation to external databases, the catalog will also define these connections.
Appoint someone as the Documentation Coordinator (DC). This individual
will be solely responsible for changing the master catalog and distributing it to
participants. All distributed copies should be set to read-only to discourage
casual changes by anyone else.
continued

Guide to documenting networks

3. Develop project design standards. These should begin with simple conventions such as background color and diagram naming conventions. They should
include layout guidelines, such as whether diagrams will show physical layouts
or logical topologies. Standards should also define hierarchical structures
from top to bottomaround which the project will be built.
Publish these standards, and publish them again whenever they change. Design
standards promote consistency among contributors. Each participant should be
able to understand documentation made by anyone else in your organization.
4. Assign responsibilities. Divide the work in ways that fit your organization.
For example, you could have each facility manager document everything in his
or her own site. Or you could assign people to document single technologies,
such as videoconferencing or frame relay, throughout the entire organization.
Again, be certain everyone knows the assignmentsso that every task gets
done, but no task gets done twice.
5. Identify and integrate data. Locate information that will be recorded in your
documentation. If data is in databases or spreadsheets, then the DC must define
(in the catalog) connections through netVizs database interface (this is the easiest way to populate diagrams and update data). If data cant be directly accessed by netViz (e.g., if its in printed form), then organize it for importing or
manual entry.
6. Create and integrate projects. This is where everyone really goes to work.
The DC plays a central role.
a. DC prepares a master netViz project (based on the master catalog) documenting the diagrams in the network hierarchy.
ABC
Corp.

Chicago

HQ

Paris

b. DC e-mails the master catalog and master project files to each participant.
continued

10

General strategies

c. Each participant creates the subproject for which he or she is responsible,

working in their copy of the master project. When complete, each new subproject is exported as a new file ( Tools / Export / SubProject... ), which is emailed to the DC.
ABC
Corp.

Chicago

HQ

Paris

Tools / Export /
Subproject
(with subnet)

Paris

d. DC imports separate subprojects into the master project ( Tools / Import /

Project... ) and adds the top level links (e.g., WAN connections between sites).
ABC
Corp.

Tools / Import / Project

Chicago

HQ

Paris

Paris

7. Distribute and review the master project. DC e-mails master project (and
master catalog, if it changed) to participants, or publishes the master project on
the corporate intranet.
DC reviews for completeness and consistency. Participants review for accuracy.
continued

11

Guide to documenting networks

8. Revise the documentation. How you do this depends somewhat on how data
gets into the project.

If data is accessed through netVizs database interface: The DC can update

most of the master project through the Tools / Refresh from Database... command. However, participants should carefully review parts of the master
project for which they are responsible, because not all details are tracked in
the external databases. As needed, DC uses netVizs data import facility to
update data from text files provided by other participants, or updates data
manually.

If data is imported or entered manually: Participants send text files or new

data to the DC, who updates the master project.

If a particular subproject needs more extensive work, the responsible team

member revises it, exports it and sends it to the DC (as in step 6).
9. Back up all files! Your master catalog, master project and related files (e.g.,
backgrounds, symbols, databases) are valuable resources for managing your operation. Implement backup procedures so you can quickly recover from any
loss.

Other documentation project management tips:

Depending on your organization, you may want each team member to perfect
their part of the documentation before it is centrally integrated.

Depending on your organization, you may want participants to independently

maintain their parts of the documentation over the long term. Periodically, they
send their subprojects to the DC, who imports them into the master project and
distributes the result.

Before meetings, distribute a full set of the current documentation. Attendees

can review it and be better prepared to contribute during the meeting.

When preparing monthly reports to your boss, include some or all of the documentation. Copy and paste diagrams (or export diagrams as WMFs and import
them) into your word processing program. Or refer your boss to the entire
project in HTML form.
continued

12

General strategies

Once documentation is available, many day-to-day activities of site engineers

now depend on that documentations accuracy. Consider including documentation maintenance as an item in performance reviews.

[Shameless plug] netViz Corp. offers a variety of services that can help you
plan and carry out documentation projects. Contact us for details about:

Training programs. This is an excellent way to both train team members

and get them thinking on the same wavelength about network documentation
issues. Both basic and advanced courses are available. We can run courses
in your facilities or ours.

Consulting services. If you are facing a large, complex or particularly demanding documentation project, get help from people who have done it before. We will work with you on all aspects of a project, from analysis and
design to implementation and roll-out.

Easier network
management!

Whats for
lunch?

More efficient
troubleshooting!

A documentation project plan helps

coordinate everyones thinking

13

Guide to documenting networks

14

Basic design issues

15

16

Basic design issues

Defining data fields

Question:

I understand the basic difference between text and list fields. When Im defining
objects, though, Im not always sure which kind to use. What do you suggest?

Answer:

It depends on what kind of data you want to record in a field.

List fields are best when the entry can be chosen from a specific set. For example, there are only certain choices for CPU type or a modems baud rate.
List fields force consistency, eliminate typing and minimize errors. The first
list item is the fields default entry, so set it to the most-used value.
However, a list field can be configured to accept a text entry not in the list. In
the catalog, set the list fields Bytes to a value greater than the longest anticipated text entry. To prevent such text entries, set the list fields Bytes to 0.

Text fields are best when you need to record relatively unrestricted information, such as user names, router addresses, autoexec.bat file contents, maintenance records and so forth. Although text fields offer flexibility, data must be
entered consistently. For example, will you enter user names as Last Name,
First Name or First Name Last Name? Formats for important fields should be
specified in your internal standards. Inconsistent formats in text fields could
result in incomplete database search results.

Question:

Oops! I defined a list field for an object and now I want it to be a text field (or
vice versa). How can I switch to the other field type without losing all that data I
entered for objects?

Answer:

There is no direct way to change from one field type to the other. However, you
can take care of this problem by using netVizs data export and import capabilities:
1. Back up all affected projects and catalogs.
2. Export the data for this object from all projects based on the catalog in which
the object is defined.
3. In the catalog, delete the field you want to change.
4. Define a new field of the other type (if the new field is a list field, also define
the list of entries).
5. Import the objects data back into each project based on this catalog.
(Part 5 in the netViz users guide describes data importing and exporting.)
This technique works best when changing from a list field to a text field. When
changing from a text field to a list field, the roster of list items should match the
set of all entries in the text field, otherwise non-matching data will be changed to
the default (first) list item.

17

Guide to documenting networks

Naming data fields

Question:

Should I be careful when defining data field names?

Answer:

When naming data fields, think ahead about how you might want to search for
data. In the Search by Data Value window (but not the Search by Type window), you select a field name and netViz searches all object types containing a
field with that name. By carefully assigning field names, you can control which
object types are included (or not included) in the search. Heres what I mean:

Example 1. Suppose the accounting department frequently asks you to track

down a piece of equipment by serial number. Bein strictly bean counters, they
cant tell you anything useful (like the manufacturers name or model number),
just the serial number.
When you set up data field names, be certain that the serial number fields in
different objects carry exactly the same name. You might choose to use Serial
Number or Serial No. or Serial #, but the name must be consistent across
all object types that record this kind of data. Then, in a search by data value,
netViz will examine all serial number data regardless of object typeeliminating the need to search different serial number field names.

Example 2. Your network has large numbers of PCs and workstations, which
are entirely different animals. When you do a search by data value on the OS
Version field to determine the operating system version for PCs, it takes much
longer because netViz searches that field for workstations, too.
Simply rename the OS Version field for one of the object types. Op Sys
Version or O-S Version are viable alternative names. Now, in the Search by
Data Value window, select the field for the target object type (as shown in the
Object Type list in that window). Since there is only one object type with that
field name, search time is minimized.

18

Basic design issues

Documenting workstations
Question:

What information should I record about workstation clients on my network?

Answer:

Design workstation node types with graphics that look similar to the equipment
they represent. A PC in a tower case should look different from a Mac in a desktop box. If you dont want to use realistic graphics, then use different geometric
shapes and colors: blue squares and green triangles, for instance. Assign a unique,
descriptive name to each node type.
Define fields to record and track information you think is important for your operations. Some suggestions are listed below. You might want to pick a core set
(e.g., serial number, CPU, memory and purchase date) that appears in all workstation object types. Others may appear in some workstation types, but not in others.

Serial number

Manufacturer

CPU (type and speed)

ROM BIOS (source and version)

RAM size (and possibly type and speed)

Drive types (floppies, hard disk, CD-ROM, etc.)

Hard disk capacities (for easier searches, specify in MB or GB, but not both)

Adapter cards (e.g., display, communication, network)

Adapter card settings (I/O address, IRQ, DMA address)

Network node identification

Network client software (version and configuration)

Operating system (name and version)

Purchase date

Warranty expiration date

Maintenance records

Physical location (e.g., building, floor, room)

User (name, phone number or extension)

19

Guide to documenting networks

Documenting cables
Question:

We already have a cable numbering system. Is there anything besides cable numbers that we should record in the documentation?

Answer:

Yes. Here is one approach and some possibilities for data fields:
1. First, create different link types (with different widths, colors and patterns)
based on the characteristic that makes cables most different from each other.
Which characteristic you choose will depend on your objectives. For example,
you could design your links around one or two of the following characteristics:

LAN technology (e.g., Ethernet or Token Ring)

Topology (e.g., Frame Relay, 10baseT or star) or

Cable type (e.g., coax or twisted pair)

The characteristic(s) you choose will control both appearances and names for
link types. For example, you could make a link type named 10baseT
Ethernet that is a medium width solid blue line.
2. Then, decide what data fields will be important for your management and information needs. Different link types can have different fields. For instance, impedance is relevant for coax, but unimportant for twisted pair. Possibilities include:

The other one or two unique characteristics not encoded by appearance and
name

Cable number

From location (e.g., building, floor, room; these could be in one or several
fields)*

To location*

From device*

To device*

Impedance

Length (sometimes useful in isolating performance problems)

Bandwidth

Protocol

*netViz automatically provides this information in Connectivity View. However, you may have reasons to embed the data in objects.

20

Basic design issues

Documenting servers
Question:

What data fields do you recommend I define for server node types?

Answer:

Much of the information in Documenting workstations (earlier in this section)

also applies to servers, so thats a good place to start. Here are some additional
data fields you might want to add to server node types:

Server name

Server type (e.g., file, printer, fax, communications)

Logical network identification

Network operating system (name, version, configuration)

Protocol stacks (e.g., Netbios, IPX/SPX, TCP/IP)

Cables in some LANs follow rather bizarre routes

21

Guide to documenting networks

22

Network documentation
techniques

23

24

Network documentation techniques

Documenting a LAN
Question:

Heres my most burning question: Just how do I document my LAN?

Answer:

netViz Corp. has had the opportunity to help a broad spectrum of organizations
document their networks. Under real-life conditions, we developed a method for
thoroughly and accurately documenting most networks. By following our approach, you will fulfill four essential documentation goals:

Document every piece of hardware in the network. To manage, troubleshoot

and grow your network, you need to know exactly what you have and where
everything is located.

Document connectivity to the level of individual cables, jacks and ports. Connectivity is the essence of a network. Your ability to troubleshoot depends on
knowing exactly what is connected to what.

Record every relevant piece of information. Comprehensive data allows you

to query your documentation, then have it tell you exactly what you need to
know.

Decompose and structure the documentation so you can see your system at
various levels of detail. Management tasks depend on your ability to see the
system as whole, its major parts and the details of individual components.

Question:

But my LAN is different from everyone elses! Will your procedure still work?

Answer:

Our plan works with most LANs, such as this typical system:

LAN spans multiple floors in a building.

10baseT connections to desktops.
CAT 5 cabling from voice and data ports, terminating in one voice jack and one
data jack per room.
Each floor has one or two wiring closets that contain patch panels to support all
the voice and data ports on that floor. Connections are made to a local hub.
Hubs are connected via fiber optic backbone to a fiber distribution panel in the
central computer room.
Servers connect through 100baseT to a central hub.

The approach can accommodate wide variations from the system described above.

25

Guide to documenting networks

Question:

Okay, that sounds like a good fit to my LAN. But what kind of documentation
will I end up with?

Answer:

Youll have a four-level netViz project thats structured like this:

Top Level: Floors and
floor connectivity
Level 2: Floor details;
end user devices (PCs, printers, etc.)
Level 3: Wiring closets,
equipment rooms
Level 4: Network devices
and connectivity

Heres what will be shown in each level:

26

Top Level diagram shows

the buildings floors and the
LAN connections between
floors. This diagram might
have a picture of the building as a background.

Network documentation techniques

Level 2 diagrams show

one floor per diagram.
Each diagram has a floor
plan as its background, and
shows all end user devices
(such as PCs and printers)
over the floor plans physical context. These diagrams also show wall jacks,
and cabling from those
jacks to wiring closets.

Level 3 diagrams show

one wiring closet or equipment room per diagram.
These diagrams contain
racks, network devices
(patch panels, hubs, routers,
switches, etc.) and servers
(file, database, web, print,
communication, etc.). As
far as possible, these diagrams mirror the hardwares
actual physical arrangement
in the wiring closet or
equipment room.

Level 4 diagrams show

one network device per diagram. Each diagram reflects the actual physical arrangement of ports and represents the actual connections from ports to other devices.

27

Guide to documenting networks

Question:

Sounds like a good plan. How do I put together a project like that?

Answer:

1. Identify the components to be documented.

a. Make a list of every kind of hardware (including different kinds of wall jacks
and cables) in the path that includes and extends from workstations to servers. Be very thorough. Include equipment racks and cabinets.
b. For each kind of hardware, list all the kinds of information you need to
record for it. For specific suggestions, see Documenting workstations,
Documenting cables and Documenting servers in the Basic design issues chapter.
2. Create the catalog.
3. Determine how you are going to create objects and embed data. Options are:

Manual. Okay when there are just a few instances of an object type (e.g.,
printers, scanners, fiber optic backbones). Use only if data isnt available
from other sources (spreadsheets, databases).

Network Discovery. Good for roughing out servers, volumes, clients and
shared printers (and certain corresponding data) in a LAN. However,
doesnt document hardware between servers and clients that you need to
know about, and wont capture lots of essential data.

Database Interface. Excellent choice if data is already recorded in spreadsheets or databases. Also a good choice for documenting client hardware if
you are using Microsoft System Management Server (SMS; see Taking advantage of SMS data later in this chapter).

Data Import. An alternative to Database Interface, but data preparation can

be more complex. Okay for one-time import, but Database Interface is better
if you expect data to change over time.

You will undoubtedly use a combination of these techniques.

4. Document the Top Level: create a node for each floor.
continued

28

Network documentation techniques

5. From the Top Level, drill down into each diagram on Level 2 and document all
components. For each Level 2 diagram:
a. Import a floor plan as the background.
b. Create wiring closets and/or equipment rooms.
c. Populate the diagram with all end user devices (PCs, workstations, printers,
scanners, etc.).
d. Populate the diagram with all wall jacks and ports.
6. From each floor diagram in Level 2, drill down into each wiring closet/equipment room diagram in Level 3 and document all devices in them. For each
Level 3 diagram create racks and equipment cabinets, then fill them with patch
panels, switches, hubs, routers, fiber distribution panels, modem banks, servers,
etc. Arrange these objects to show how the actual equipment is mounted in the
rack/cabinet.
7. From each wiring closet/equipment room diagram in Level 3, document the
cards and/or ports for each network device:
a. In the Level 3 diagram, copy the device.
b. Drill down into the devices subdiagram, then Edit / Paste As Alias. Resize
the new object, making it large enough to accept card and/or port nodes.
c. If the device has cards containing ports: populate the device with cards and
ports, then group each card with its ports and group the device with its cards.
This makes the device into a contain for its cards and each card a container
for its ports.
d. If the device has ports (but no cards): populate the device with ports, then
group the device with its ports This makes the device into a container for the
ports.
Showing port-to-port details, later, provides more information on the structures in Level 4 and why they are important.
8. In each Level 2 diagram: create links to document the short cables between end
user devices and wall jacks. Tip: see Linking to small nodes, later.
continued
29

Guide to documenting networks

9. For each diagram in Level 2: for each wall jack, create an interdiagram link to
document the cable between the wall jack in Level 2 and the patch panel in
Level 4. Tip: see Linking to small nodes, later.
10.For each patch panel in Level 4: create interdiagram links to document the
cables between patch panel jacks in Level 4 and hub ports in Level 4.
11. For each hub in Level 4: create an interdiagram link between the hubs fiber
ports and the fiber distribution panel.
12.For each server in Level 3: create links or interdiagram links to other devices.

30

Network documentation techniques

Question:

This project shows the physical structure of my LAN. What would it take to get a
logical view of the network, too?

Answer:

Its easy to construct a logical view once youve completed the physical structure
described in the previous pages.
1. In Level 1, create a generic node to contain the logical diagram.
2. In Level 2, copy all the PCs in the logical segment, IP mask or ring.
3. In Level 1, drill down into the logical diagram. Edit / Paste As Alias.
4. Locate the hub or card that supports this segment, copy it and paste it as an
alias in the logical diagram.
5. Repeat steps 2 to 4 for other segments you want to see in the logical view.
6. Add an object to represent each ring or segment in the LAN. A Line node is
good for representing segments, while a circle node can show rings.
7. Using a link type that isnt used in the physical documentation (add a new link
type to the catalog, if necessary), connect the user and network devices to the
corresponding segment or ring.
Note: These logical links will not be automatically changed if you change the
connections in the physical documentation. For example, if you switch a PC
from one segment to another in the physical documentation, you must visit the
logical diagram and manually make the change there, too.

31

Guide to documenting networks

Collecting data later

Question:

If I dont have all the data I need to record for an object type, can I enter some
data now and more later?

Answer:

Sure. Here are some suggestions for collecting and entering data:

32

Its best to forge ahead with building the graphical part of your project. Postpone data collection and entry to a time when it wont distract from project development.

If data collection will take you to different locations in your facility, its helpful
to use a laptop computer. (A netViz license allows you to install netViz on one
workstation, so you must have a separate license to install netViz on a laptop.)

The most efficient way to manually collect data is to directly enter it into your
netViz project. Table View enables rapid data entry.

You can also collect data in a spreadsheet and import it into your project.
Heres how to do that for one object type:
a. Use Tools / Export / To Text... to export data for all instances of one object type.
In the Export Options window, activate Field Headers (see the netViz
users guide for other data export details).
b. Import the data into a spreadsheet. The Field Headers identify the data fields
in the table. Youll need to fill the empty cells.
c. After youve collected the data, select all the cells in the table and export it
from the spreadsheet as a CSV file.
d. Import the data into netViz (see the netViz users guide for data import details).

netVizs Database Interface is another way to move large amounts of data into
project objects. You can pull in data from databases and spreadsheets (see the
netViz users guide for details).

Network documentation techniques

Showing port-to-port details

Question:

Your Documenting a LAN procedure seems like a lot of trouble. Couldnt I just
draw my system like this?
PC

PC
S
e
r
v
e
r

PC
PC

PC
PC

PC

Answer:

PC

You could, but youd be leaving out a lot of vital informationdetails you need to
efficiently manage your network.
Lets take a closer look at a typical well-designed network. There are usually several components between a server and a workstation. In abstract form, the components and interconnections might be as follows:
Component

What you often need to know

Server

Which server?

|
|
|
|

Hub

cable

Which cable?
Which hub in which rack? Which hub port?

cable
Patch panel

Which cable?
Which patch panel in which rack? Which connector?

cable
Wall jack

Which cable?
Which wall jack?

cable
Workstation

Which workstation?

For starters, your diagrams need to contain all these components. While you drew
the logical connections in your simple diagram above, what you really need to
show are the actual components and connections.
To answer the questions listed above, you could laboriously record from/to details
in each components data fields. However, this means that if you change a single
connection in a diagram, youd have to carefully enter new data in three places
(source component, cable and destination component).
continued

33

Guide to documenting networks

On the other hand, a properly structured netViz project can automatically answer
these questions. For example, you can examine the diagram for a patch panel and
quickly determine exactly which hub port and wall jack is attached to each connector. Further, when you change a connection in a diagram, netViz automatically
keeps track of the from/to data for you.
The key is to take advantage of several netViz capabilities, including multilevel
projects, interdiagram linking, aliases, grouping and Connectivity View. Ill
show you how in the next few pages.
The next two figures show one way to document the components and connections
between a server and a workstation. This isnt the only way, nor is it necessarily
the best way for your particular network. It does, however, show techniques for
structuring your documentation so you can easily extract information from it. And
its done according to the procedure in Documenting a LAN.
In the first figure (on the next page), Ive shown a few components relevant to our
example. For clarity, I left out the Top Level and a lot of hardware. Heres whats
in the project...
The Level 2 diagram shows a wall jack and a workstation using the appropriate
node types. The Equipment Room can be a generic rectangle node. Its main purpose is to provide a subdiagram containing more details.
The Equipment Room diagram in Level 3 contains a couple of server nodes and a
couple of rack nodes. Patch Panel C and Hub D are superimposed on Rack 1
(other equipment in Rack 1 isnt shown here). It will help in tracing connections
to make Rack 1 a container for Patch Panel C and Hub D using the Object / Group
command (see netViz users guide for details).
To create the Hub D diagram in Level 4, copy the Hub D node in Level 3, drill
down into Hub D, then Edit / Paste as Alias. This makes a second instance of Hub D
in its own subdiagram. Add ports inside Hub D, then use grouping to make Hub
D into a container for its ports. Create the Level 4 Patch Panel C diagram in the
same way.
Tip: Youll find it easier to follow this example if you actually create this project in netViz. Open all the diagram windows, then arrange them so they are in about the same relationships as in the
illustration on the next page.

continued
34

Network documentation techniques

Level 2 diagram: Floor 5

[possibly containing floor plan (not shown); only one wall jack and workstation shown for clarity]

Wall Jack J31

Equipment Room node

Workstation W08

Level 3 diagram: Equipment Room

Rack 1

Rack 2

Phone system

Patch Panel C
Server 1 Server 2
Hub D

Level 4 diagram: Hub D

Level 4 diagram: Patch Panel C

Hub D ports

Patch Panel C connectors

Hub is an alias in its own subdiagram and

this instance is a container for the ports

Patch panel is an alias in its own subdiagram and

this instance is a container for the connectors

35

Guide to documenting networks

Now lets add links to connect the workstation to the server. You can follow along
in the figure on the next page. Each link is numbered to correspond to the steps
below.
1. In Level 2, drag a link between Workstation W08 and Wall Jack J31. This link
represents the short cable connecting the workstation to the wall jack.
2. Create an interdiagram link between Wall Jack J31 and connector 7 in the Patch
Panel C subdiagram (see the netViz users guide for interdiagram linking details).
This link represents the long cable that runs up inside the wall, across the ceiling tiles and down into the equipment room.
netViz automatically creates a Wall Jack J31 reference node in the Equipment
Room diagram, which shows here that the jack connects to Patch Panel C.
netViz also creates a Wall Jack J31 reference node in the Patch Panel C diagram
(in Level 4) to show it attaches to connector 7.
3. Create an interdiagram link between connector 7 in the Patch Panel C diagram
and port 5 in the Hub D diagram.
This link represents the patch cord between the patch panel and the hub.
netViz automatically creates a Hub D port 5 reference node in the Patch Panel
C diagram, and a Patch Panel C connector 7 reference node in the Hub D diagram to show this interconnection. netViz also shows this connection in the
Equipment Room diagram.
4. Create an interdiagram link between Hub D port 8 and Server 2.
The diagrams now give you lots of useful information. For instance, you can instantly see connections to and from Patch Panel C. However, when you fill up
these diagrams with dozens or hundreds of workstations, wall jacks, patch panel
connectors and hub ports, theyre more difficult to readeven if you turn off data
displays to reduce clutter. As usual, netViz has a solution: Connectivity View.
continued

36

Network documentation techniques

Level 2 diagram: Floor 5

[possibly containing floor plan (not shown); only one wall jack and workstation shown for clarity]

Wall Jack J31

Equipment Room node

Workstation W08

Level 3 diagram: Equipment Room

Rack 1

Wall Jack J31

Phone system

Patch Panel C

[reference node]

Server 1 Server 2

Rack 2

Hub D

Level 4 diagram: Hub D

Level 4 diagram: Patch Panel C

Server 2

Port 5 in
Hub D

[reference node]

[reference node]

Hub D ports

Patch Panel C connectors

Connector 7 in
Patch Panel C
[reference node]

Wall Jack J31

[reference node]

37

Guide to documenting networks

Connectivity View (View / Connectivity) shows interconnection details without the

graphical context. Its one of the best ways to trace cables in large, complex systems.
Here are two examples of how you can use Connectivity View:

With the Equipment Room diagram showing, change to Connectivity View.

Open the Rack 1 group in the Nodes column, then click on Patch Panel C. In
the Connections column, youll be able to identify all the cablesand their remote terminationsconnected to the patch panel. You can also see that Hub D
is located in Rack 1 (the grouping function makes this fact readily available).
Additionally, Connectivity View shows that Wall Jack J31 is on Floor 5.

Double-click on Patch Panel C. The Patch Panel C diagram opens. Change to

Connectivity View. Click on Connector 7 in the Nodes column. The Connections column shows similar data, but now you know the specific hub port.
A patch panel is often your best vantage point for tracing cables. This view
shows the complete path (cables and hardware) from Wall Jack J31 through
Patch Panel C to port 5 in Hub D.

38

Network documentation techniques

Question:

Can this port-to-port technique be used to document my telephone system, too?

Answer:

Sure. In this case, youll record the connections between telephone desksets and
the PBX or other telephone equipment. You can even show connections between
your equipment and telco hardware.

Question:

How do I handle the documentation when an employee moves from one office to
another?

Answer:

Patch panels provide flexibility for employee locations. When someone moves to
a different office, you simply swap patch cords at the patch panel. This allows the
employee to keep the same network address and telephone extension number.
With documentation structured as Ive described, you can easily identify the wall
jack, cables and connectors associated with a particular employees workstation.
Heres all it takes for the documentation to stay current:
1. In your netViz project, open the patch panel diagram.
2. Find this employees patch cord linkthe one between the patch panel and the
hub (tip: the employees old wall jack is hard wired to the same patch panel
connector).
3. Drag the patch cord link from the employees old patch panel connector to the
connector hard wired to the employees new wall jack.
netViz automatically updates the connectivity information. Switch to Connectivity View to verify the new connection.

39

Guide to documenting networks

Documenting patch panels

Question:

Can my documentation make sense of the patch panel cabling nightmare?

Answer:

Weve experimented with several approaches to patch panels and one, shown below, merits our recommendation. Your objective is to clearly show the relationship between whats at the remote end of the cables attached to the back of the
patch panel and whats at the remote end of the patch cords plugged into the front.
In a diagram containing the patch panels alias, draw two rectangles. Group patch
panel connector nodes in order in the alias; arrange reference nodes hardwired to
the panels rear in the top rectangle; arrange reference nodes connected via patch
cords to the front in the bottom rectangle. Vertically align the reference nodes.
Use Diagram / Hide / Interdiagram Links to reduce visual clutter.
Interconnected nodes are
vertically aligned
Rear
connections

Patch
panel

Front
connections

Reference nodes connected

to cables hardwired to rear
of patch panel
Patch panel connector nodes
grouped in sequential order
within patch panel alias
Reference nodes connected
to patch cords plugged into
front of patch panel

The simple case: a single-row patch panel

Rear
connections

Patch
panel
alias

Use same color

rectangles for visual
identification of
corresponding rows

Front
connections

A more typical situation: a multi-row patch panel

40

Network documentation techniques

Viewing logical networks and protocols

Question:

I documented my network in great detail. Since I wanted to see the entire network
at one time, I put it all in one diagram and didnt use subdiagrams. But there are
so many nodes and links, its difficult to single out individual subsystems. How
can I view just certain logical networks or protocols?

Answer:

Use view filters or alias objects to modify your view of the network. View filters
let you hide non-selected objects. Aliases are used to depict an object in multiple
locations throughout a project.
Example 1: You have Frame Relay, ATM, ISDN and satellite communications in
your WAN. Some sites have a combination of these protocols, and some switches
support multiple protocols. Your documentation is based on the physical topology, but youd like to see just one protocol or subnet at a time.

ATM
ISDN

Frame Relay

Satellite

A multi-protocol WAN

Solution 1: Use filtering by instance. Select a protocol cloud, invoke Diagram /

Filter Options... , then activate Display Normal in the Connected Objects section.

ISDN

Frame Relay

Filtered to show the Frame Relay protocol...

or the ISDN protocol

41

Guide to documenting networks

Example 2: You documented your complex hub-and-spoke network in a single

diagram so you could see everything at once. However, sometimes you need to
isolate various levels for presentations and other activities. For instance, you want
to see just the backbone network (the hubs and their communication links) or just
certain subnets.

A hub-and-spoke network

Solution 2: Use filtering by instance (select what youd like to see, then Diagram /
Filter Options... ). Use this approach when you need to see only some instances of
one or more object types, while hiding the other instances.

View just the backbone...

42

or whats connected to one hub

Network documentation techniques

Example 3: Your LAN is completely documented from the physical standpoint.

Everything is shown, from servers, hubs and workstations to every cable and wall
jack. In your work, though, you need independent views of the NetWare, TCP/IP
and AppleTalk networks. You could use Copy and Paste to create what you need in
other diagrams, but then when data changes in the main diagram youd have to
make the same changes everywhere else. What can you do to avoid maintaining
data the hard way?

A B C

The complete LAN diagrammed over a floor plan

Solution 3: Diagram other topologies by pasting aliases (rather than duplicating

or copying objects). An alias is a separate instance of an object. Change data in
an alias and its automatically changed in all other instances.

Another diagram showing the NetWare subnet

as aliases...

and another diagram showing the AppleTalk

subnet as aliases in server-centric views

43

Guide to documenting networks

Combining physical and logical views

Question:

Earlier, in Showing port-to-port details, you made a good case for documenting
every network component in a multilevel project. Then in Viewing logical networks and protocols you pointed out the advantages of alternate views. Whats a
good way to combine these approaches?

Answer:

Here are a couple of examples showing how you might logically diagram an
Ethernet or Token Ring LAN.

Server 1
Segment 1

Server 2

Segment 2

Server 1

Ring 1

Server 2

Ring 2

Logical diagrams have three advantages:

Topology at the link level is implicit.
Segments or rings are clearly visible (allowing, for example, quick load estimates).
Logical diagrams are easy to draw and understand.
However, logical diagrams have a downside:
A lot is missing: the actual cabling isnt shown, and many important network
devices (such as hubs and routers) are left out.
They arent good for diagnosis and troubleshooting.
continued

44

Network documentation techniques

In contrast, physical diagrams, by recording every

detail, are essential for real-life problem-solving.
This approach takes longer to construct, but its
worth it to have real information at your fingertips. On the other hand, with components spread
out over several diagrams, the physical approach
can obscure logical relationships.

PCs

Jacks

Rack

Patch
Panel
Server
Hub

As usual, netViz provides a solution, allowing you to combine the benefits of both
approaches...
First, document the networks physical topology (so youll have all the information you need for efficient troubleshooting). Then, identify the hubs or MAU/
MSAUs that constitute the logical segments or rings. Here are a couple of ways
to add logical information:

Use netVizs grouping function to combine hubs/MAUs into logical units (next
page, left side). In Connectivity View, each group container can be expanded
to list its interconnections.

Create a node to represent each logical unit (next page, right side). In this case,
ellipses behind the Equipment Rack indicate segment rings. In the physical
diagram, copy the logically interconnected workstations, then paste them as
aliases in the segment logical subdiagram. Copy the segment node and paste it
as an alias in its own logical subdiagram. Finally, in the logical subdiagram
CTRL-drag new links (each representing several physical cables) between workstations and the segment node alias. By using aliases, you preserve the integrity of the database so that different instances of the same object point to a
single data record.

You can use these same techniques to add other topologies, such as workgroups
(based on disk volume or application) or domains.
continued

45

Guide to documenting networks

Using groups: Hub 1 and Hub 2 are grouped

within Segment 1

Using aliases: Segment 2 subdiagram contains

aliases to show logical interconnections

Equipment Rack

Equipment Rack

Patch Panel 1

Patch Panel 1

Patch Panel 2

Patch Panel 2

Segment 1

10-baseT Hub 1

10-baseT Hub 1
Segment 1

Segment 2

10-baseT Hub 2

10-baseT Hub 2

10-baseT Hub 3

10-baseT Hub 3

10-baseT Hub 4

10-baseT Hub 4

10-baseT Hub 5

10-baseT Hub 5

Segment 2

Segment 2 sub-diagram

Segment 2

Caution: In the logical segment diagram above, the links reprewall jack
sent composite connections (e.g., workstation
patch panel
hub). You must manually create and maintain
these logical links. For instance, if one of the physical links in the
composite is modified or deleted (so that the composite is no
longer valid), netViz will not automatically update the corresponding connections in the logical diagrams.

46

Network documentation techniques

Taking advantage of SMS data

Question:

I use Microsofts System Management Server to help me manage the Windows

NT network here. Can netViz projects tap into the data SMS collects?

Answer:

Yes, using the Database Interface feature in netViz Professional Edition. Heres
how:
1. On the SMS server, at the DOS prompt, run the following command:
.\sms\site.srv\x86.bin\smsview
This causes SMS to generate dozens of views or tables that can be accessed
through ODBC using SQL queriesa natural fit for the netViz Database Interface. (The SMS data, stored in tables in the same database, is directly accessible through the netViz Database Interface, but is probably not as useful as the
generated views.)
2. Open the netViz catalog which you want to connect to SMS data.
3. Tools / Connect to Database Table... .
4. In the Connect to Database Table window, in the Select Database Type list,
click SQL Server Database.
5. Click the Get Tables and Views button.
6. In the SQL Server Login window:
a. Select a Server.
b. Enter a Login ID.
c. Enter a Password, if required.
d. Select the SMS Database.
e. Click OK.
7. Back in the Connect to Database Table window:
a. In the Select Table or View list, activate the tables you want to use.
b. For selected tables, click the Select Key button and assign a key.
c. Click OK.
8. Connect table fields to object data fields (see Database interface: basic in the
netViz users guide for details).
continued

47

Guide to documenting networks

Question:

SMS collects and maintains huge amounts of data about network clients. Of that
data, whats relevant for my netViz documentation?

Answer:

I cant tell you what is meaningful, because that depends on your particular management requirements. However, you might start with some of these tables:
For data about...

look in these SMS views...

Computers

vNetwork, vOperating_System, vPC_BIOS, vPC_Memory, vProcessor,

vDisk, vNetCard

Disks

vDisk

Network Card

vNetCard

Video Card

vVideo

continued

Question:

What is SMS?

Answer:

Some of you folks with smaller networks may not know about
Microsofts System Management Server (SMS). SMS is a Windows
NT product that makes it easier to centrally manage, support and
maintain a distributed computer network. SMS is part of the
Microsoft BackOffice family.
SMS allows you to perform a variety of management tasks, ranging
from identifying how many computers you have on your network to
monitoring network integrity. Its main functions include hardware
and software inventory, software distribution, software application
sharing and remote troubleshooting.
SMS collects a vast array of data, any of which you can make available in your netViz documentation. This section shows you how to
use that data by connecting SMS-generated tables to netViz object
types through the Database Interface (available in netViz Professional Edition).

Question:

Beyond the information youve provided here, can I call netViz Corp.
for help in installing and understanding SMS?

Answer:

netViz Corp. doesnt provide support for this Microsoft product.

However, our consulting services group is available on a contract
basis to configure the Database Interface for your particular needs.

SMS keeps you plugged into network goings-on.

48

Network documentation techniques

Question:

Sounds pretty easy. Any catches?

Answer:

There are a couple of things you should be aware of:

Step 1 never needs to be repeatedthe views are automatically updated by

SMS. However, when the views change, new data wont immediately show up
in the netViz project. Periodically, you should refresh data in your project
(Tools / Refresh Project from Database... ).

It is possible to connect the keys of several tables to one netViz object key.
This makes sensein a project you can use one field to bring in a variety of information about a network component from the multiple tables that describe it.

Three tables have their

keys connected to this objects key. The table on the left
was connected first, so its key data appears in the Inspector.

When you do this, be aware that:

The table making the first key-to-key connection determines the data values
appearing in the key field drop-down list in the Inspector. (The first key-tokey connection is the wide blue line; subsequent key-to-key connections are
narrow blue lines.) This is significant because...

Even though different SMS tables have the same key field names, the data in
those key fields may be different. For example, a workstation is listed in one
table because it has spreadsheet software installed, but it isnt listed in the
word processor table because it doesnt have word processor software installed.

When using multiple tables in this way, your best strategy is to determine the
table whose key is most inclusive, then connect that tables key to the object
type key before connecting other tables.

49

Guide to documenting networks

Linking to small nodes

Question:

Ive made certain nodes, like wall jacks and ports in cards, really small (as they
should be). How can I keep from going nuts trying to link to these tiny objects?

Answer:

You can eliminate this tedious and error-prone work by using the Data Export and
Data Import capabilities in netViz.
1. Export data for the From and To node types.
2. Import the files into a spreadsheet program, such as Excel.
3. Set up a new worksheet that contains columns for the link keys, the From
node keys and the To node keys. Copy and paste the From node keys and
the To node keys to this worksheet.
4. If necessary, rearrange the data so that From node keys match the To node
keys they actually connect to. Here is what the spreadsheet might look like after three To keys have been matched to From keys:

5. Fill in the link keys (column A in this example) with unique values.

6. Export the table cells from the spreadsheet as a CSV file.

7. In netViz, import the CSV file. In the Select Object Type window, match the
incoming data fields to the link object types fields if necessary.
netViz reads the data file and draws the links. (Instead of importing the file, you
could use the netViz Database Interface capability; see the netViz users guide for
details).

50

Other techniques

51

52

Other techniques

Change control*
Question:

My organizations network is constantly changing, and there always seems to be a

lot of confusion about whats changing, whos going to take care of it and when it
will be done. How can I use netViz to make sense of all this?

Answer:

netViz makes change control a snap.

First, define a node type for change control. Use a square as the symbol and give
it distinctive colors (yellow with a wide red border works for me). Define data
fields that cover everything you need to know about a change: who asked for it,
what is to be changed, who is responsible, when it is completed and so forth. The
Inspector below provides some suggestions. Depending on the nature of changes
in your organization, you may want to make some of the fields fairly large (dont
forget to increase their Bytes, too, so they will actually hold as much information
as they promise visually).
Tip: The example change control node shown here is defined in
the catalog change.cat in the Examples directory of the netViz CDROM. You can add this node type to any catalog using the Tools /
Merge Catalogs... command, then modify it to suit your needs.

Data fields in a typical

change control node

continued

*Inspired by netViz user First Data Corp.

53

Guide to documenting networks

Heres how to use this change control node type:

1. When you receive notice of a change:
a. Drag a change control node into the affected diagram. (If you accept the default key field data that netViz assigns, each change control node will be sequentially numberedwhich can be used later for audit purposes).
b. Resize the new node to surround the affected objects, as shown below.
c. Object / Reorder / Send to Back to put the change control node in back.

Change control node surrounding

objects to which it applies

d. Optional: Group the change control node with the nodes it affects.
e. Open the Inspector and fill in everything you know about the change (you
can always add more information later).
Tip: If the change involves interconnections, create a nested group
with the change control node as the container (outermost object).
Now, when you switch to Connectivity View to trace cables, all the
affected nodes show up together under the change control node.

2. Some changes involve multiple areas within the organizationand within the
documentation. For example, moving workstations from room to room may
also cause changes at patch panels in the central equipment room. With this
kind of change, use aliases to create additional instances of a change control
node in other diagrams.
3. Use netVizs search function to generate work orders for service technicians or
others who are actually making the changes.
a. Tools / Search by Type... .
b. Select the change control node as the Object Type.
c. In the Data Field list, click the Person Responsible or similar field.
d. In the Values box, type the name of a service technician.
e. Click Search.
f. In the search results window, format and print the table.
continued
54

Other techniques

Tip: If service technicians have access to the project, they can do

their own searches (even while on site) using step 3.

4. When a change is complete:

a. Fill in the date completed (or similar) field for the corresponding change
control node.
b. Update the project to reflect the change.
5. Consolidate completed changes (for CYA purposes):
a. Create a page in the Temporary Workspace devoted to completed changes.
b. Search for change control objects having the date completed (or similar)
field filled in.
c. Go to the diagram containing each completed change, then:
Ungroup the change control node (if it was grouped), cut the change control node, then paste it in the special page in the Temporary Workspace.
or
Copy the change control node, go to the special page in the Temporary
Workspace and Edit / Paste As Alias.
If you have a formal change control audit program, dont delete a change control
node created by mistake. Instead, enter VOID in one of its non-key fields, then
immediately move it into the Temporary Workspace.

Question:

What kinds of changes should I track?

Answer:

Anything that affects your network and your documentation. Also, watch for
people outside the network management group making changes: users, consultants, contractors and upper level executives. These people often dont even know
your documentation exists, much less that they should tell you when theyve
mucked around in the system. Client hardware and software are particularly vulnerable to undocumented
changes. Keep your eyes open and listen to the grapevine... then make a quick check after any suspected covert activity.
How do you catch changes that didnt get into the
documentation through your change control system?
Occasionallymaybe once a quarteraudit the entire network and update your records.
netViz eliminates paper-based change control
55

Guide to documenting networks

Reassigning data to the key

Question:

Ive been tracking PCs with users name (labeled Name) as the key. I now want
to change the key to PC serial number, which Ive already defined for the PC object type and dutifully recorded in the Inspector for each PC. Whats the easiest
way to switch the data from the Serial Number field to the key field?

How do I swap data in the key field...

Answer:

with data from another field?

1. As usual before making any radical change, back up your project and catalog
files.
2. Assure that each PC has a unique key (i.e., there isnt more than one PC identified as John Smith, for example). Use Tools / Search by Type... to find all instances of the PC object type, then sort the Name column. Review for duplicate user names.
3. Export data (Tools / Export / To Text...) for the PC object type only.
4. Open the resulting CSV or TXT file in a spreadsheet. Then:
a. Insert a new column to the left of the Name column. Enter $newKey as
the header for this column. Cut the serial numbers and paste them in the new
column.
b. Change the header of the Name column to $oldKey. (Meaning: when
you import this data, netViz will look for each user name in the key field,
then substitute the corresponding serial number.)
c. If you want to keep user name as a separate field for the object type, copy all
the user names, then paste them in an empty column. Enter User Name as
the header for this column.
d. Save the document in CSV or TXT format.
continued

56

Other techniques

5. Open the netViz catalog for this project. In the catalog:

a. Delete the Serial Number field.
b. Change the label for the key field to Serial Number. If necessary, adjust
the string length (Bytes) to accommodate the longest anticipated serial number.
c. If you are retaining user name data, then create a new field labeled User
Name.
d. Save the catalog.
7. Open the project. In the project:
a. Tools / Import / From Text... .
b. Select the revised text file, then click OK.
c. In the Select Object Type window, select the PC node type, then match the
incoming data fields to the fields defined for the node type (see netViz users
guide for details about importing data). Click OK.

57

Guide to documenting networks

Formatting text
Question:

How can I improve readability of data fields and text blocks in diagrams?

Answer:

In general, for best on-screen readability:

Use sans serif fonts like Arial and Helvetica. Use Normal or Bold styles.

Avoid serif fonts like Times New Roman. Avoid Italic and Bold Italic styles.

Limit fancy fonts to larger sizes, such as used in titles and logos.

Use only outline fonts (TrueType or Postscript). Dont use bitmapped fonts,
since these dont scale smoothly.

The medium in which your documentation will be viewed most often may influence your choice of fonts, sizes and styles:

58

Primarily netViz or netViz Viewer on-screen viewing: The ability to zoom in

and to use the Inspector and Table View to review data broadens the range of
suitable fonts.

Primarily other on-screen viewing (e.g., diagrams are images within other
documents or HTML pages): Zooming in may not be an option, so type should
be in a font and size thats readable in the ultimate destination. Export a diagram and view it in the other application, and have other people try reading
critical information from it. Adjust text formatting as needed.

Primarily hard copy printouts: Printer resolution usually permits a wide range
of fonts, sizes and styles.

Other techniques

Question:

How can I put characters like , , , and into data fields and text blocks?

Answer:

1. In the Windows 95 Start menu, click Help.

2. Click the Index tab, search for and click on special characters, inserting, then
click the Display button.
or
Click the Find tab, then search for special and click on Inserting a special
character into a document, then click the Display button.
3. Follow the instructions in the Windows help topic that appears, including opening the Character Map window in step 1 of that topic.
4. In netViz, place the cursor at the desired location in a data field or text block,
then press CTRL-V (or right-click in the field and click Paste in the pop-up menu).

Question:

How can I set up numbered paragraphs, bold or underlined words, indents and
other formatting in text blocks?

Answer:

netViz doesnt offer the same level of formatting that your word processor does.
For example, there cant be a Bold word within a text block set to the Normal
style. However, there are some tricks that will help you achieve most formatting
goals:

If a word, phrase or paragraph needs to be different than the surrounding text,

then put it in its own text block.

Turn on the grid (Diagram / Grid Settings... ; activate Snap to Grid and set Grid
Spacing to 16 per inch or 32 per inch). The grid simplifies horizontal and vertical alignment between different text blocks. When you need to precisely position
a text block (e.g., a Bold word in front of its paragraph), turn the grid off.

Put numbers (or bullets) in tall, narrow text blocks, and use CTRL-ENTER to add
blank lines so numbers (or bullets) horizontally align with corresponding paragraphs.

When youve finished building a set of formatted text blocks, select and group
them (CTRL-G) so everything stays together.

The example on the next page shows a formatted paragraph and its constituent
text blocks.

59

Guide to documenting networks

A nicely formatted section of text...

and the text blocks from which it is built...

A floor plan built in netViz (see next page)

Room 109

Room 107

Room 105

Room 103

Room 101

RESTRICTED
AREA

North Hall

Room 110

Room 108

Room 106

Room 104

Room 102

South Hall

Room 111

60

Room 112

Room 113

Room 114

Room 115

Other techniques

Making floor plans

Question:

I dont have floor plan graphics for my building in computer-readable form. Is

there some quick and easy way to make floor plans for diagram backgrounds?

Answer:

You can make reasonably good floor plan graphics with netViz:
1. Get an idea of the room layout. If you have a blueprint, thats a good place to
start. Otherwise, just walk around and make a sketch of the rooms and halls in
the area of interest. For most network documentation, you dont need exact dimensionsjust a rough idea of room sizes and how the rooms fit together.
2. In the Temporary Workspace, set up a new page devoted to the floor plan.
Activate snap to grid (Diagram / Grid Settings... ). This will make it easier to align
rooms and walls.
3. Create each room using a single line from the Draw palette. Add bend points
(ALT-click) as needed.
4. Floor plans often have many identical or similar rooms. Once youve drawn a
room, duplicate it (CTRL-D) to create more. Reshape the copies for different
room sizes. Use Object / Flip Horizontally and Object / Flip Vertically for different orientations.
5. Move the rooms into their final positions. If desired, leave space between
rooms so links can be routed through the walls between rooms. Add room
numbers.
6. If desired, for each room:
a. Create a rectangle the same size as the room.
b. Object / Reorder / Send to Back, and position the rectangle under the room outline.
c. Set the rectangles fill and line color to white.
This helps the room stand out in front of a gray page (see example on previous
page).
7. When you are finished creating the floor plan, Diagram / Save As Graphic... to export it as a WMF.
8. Open the diagram where you need the floor plan. Diagram / Background / Select...
to import the graphic.

61

Guide to documenting networks

Keeping multiple legends in agreement

Question:

Our diagrams include legends to help people understand what they are looking at.
But when I change whats in one legend, I have to visit dozens of diagrams to
change all the others. Is there a better way?

Answer:

Take advantage of the alias function. Recall that it works with text blocks and
draw objects as well as nodes and links. To use aliasing for a legend:
1. Set up one legend to contain all the graphics and text you need. Keep annotations separateput each one in its own text block.
2. Select everything in the legend, then Edit / Copy.
3. Go to each diagram where you want the legend and Edit / Paste As Alias.
Now when you change something in one instance of the legend, the change automatically appears in all other instances.

62

Other techniques

Improving bitmapped graphic appearance

Question:

The bitmapped backgrounds and graphics in my diagrams look awful. They look
even worse when I export the diagrams and use them in presentations, or when I
use netVizs HTML Export to make Web pages. What can I do to make graphics
look better?

Answer:

Here are typical bitmapped graphic problems and their causes:

Graphic has patterns where you expect solid colors. Cause: graphic contains dithered colors. Moires appear when background is scaled to fit within
diagram margins, printed or exported to another application (where it might be
scaled differently).

Graphic colors change when you switch between two or more visible diagrams. Cause: 256-color graphics displayed on a 256-color system can have
different color palettes; the system uses only one palette at a time, so false colors appear in the inactive diagram(s).

Graphics in GIFs generated by HTML Export have incorrect colors.

Cause: netViz exports diagrams using the default GIF palette, which may be
different that the graphics palette. This can also be affected by the browser
used to view the pages, as well as the platform (PC, Macintosh or Unix) the
browser is running on.

Graphics look good on a desktop system, but look bad on a laptop. Cause:
todays desktop PCs usually support 16-bit color depth (thousands of colors) or
24-bit color depth (millions of colors), while laptops are often restricted to 8-bit
color depth (256 colors), which cant accurately render full color images.

The following general procedure (for Photoshop, Paint Shop Pro and similar image editing programs) can help you produce bitmapped graphics that display reasonably well:
1. If possible, begin with a 24-bit image having a high resolution (300 dots per
inch is good.)
2. If file size is an issue, change the images resolution to about two times the
resolution needed for the most critical use (e.g., screen display, laser printout,
Web page). For example, if you will be printing the netViz diagram on a laser
printer, the images resolution should be at least 170 dots per inch (two times
the 85 lines per inch typical of laser printer halftones). On the other hand, if
the graphic will only be viewed on a computer monitor, the resolution can be
144 dots per inch (two times 72 dpi).
continued
63

Guide to documenting networks

3. Resize the image (downsample) to the physical dimensions needed for its most
critical use. This will minimize problems caused by scaling.
4. Reduce the images color depth to 8 bits (256 colors) using the System or
Windows palette and no dithering. Dont use an optimized or adaptive palette. (Experiment with dithering; diffusion dithering or error diffusion may
produce slightly better image quality without introducing pattern effects later.
Dont use pattern dithering.)
5. Save the image in Windows Bitmap format.
Some bitmapped images (e.g., logos) started out as vector graphics (e.g., in WMF
format). If you can locate the original vector file, use it instead of the bitmapped
version. Vector graphics scale smoothly. However, dithered fills may still appear
as patterns.
An in-depth discussion of color image processing, palettes, and browser and
cross-platform issues is best left to the experts. One good place to look for more
information is Helpful links for Web builders: image and color problems, at
http://www.arcade.uiowa.edu/proj/webbuilder/img-color.html.

64

Other techniques

Putting HTML output in frames

Question:

netViz makes it easy for me to export my diagrams as Web pages. Is there something I can do to dress up netViz-generated HTML documentation?

Answer:

Try putting your HTML pages in a frame within a Web page. The HTML example
code below displays three frames:

The top frame could contain your organizations name or logo, and introductory
or identification information for the documentation.

The center frame displays the netViz-generated documentation, one page at a

time.

The bottom frame could contain navigation instructions or contact information.

Code controlling the contents of each frame is stored in separate HTML files
(TopFrame.htm, nvFrame.htm and BtmFrame.htm). Substitute the name of your
netViz-generated top-level HTML file for nvFrame.htm. There should be no other
tags in the code which describes the frames.
<HTML>
<! netViz pages in a frame >
<HEAD>
<TITLE>Home Page</TITLE>
</HEAD>
<FRAMESET ROWS="8%,85%,*">
<FRAME SRC="TopFrame.htm" NAME="TopFrame" FRAMEBORDER="1"
MARGINWIDTH="0" MARGINHEIGHT="0" SCROLLING="NO" NORESIZE>
<FRAME SRC="nvFrame.htm" NAME="netVizFrame" FRAMEBORDER="1"
MARGINWIDTH="0" MARGINHEIGHT="0">
<FRAME SRC="BtmFrame.htm" NAME="BtmFrame" FRAMEBORDER="1"
MARGINWIDTH="0" MARGINHEIGHT="0" SCROLLING="NO" NORESIZE>
</FRAMESET>
</HTML>
The amount of space devoted to each frame is defined by the ROWS attribute of
the FRAMESET tag. In this case, 8% of the browser window is for the top frame,
85% is for the middle frame, and the bottom frame gets the remainder (see example, next page). The COLS attribute could be used in place of ROWS to create
side-by-side frames.

65

Guide to documenting networks

netViz HTML page without frames

netViz HTML page in center frame

66

Other techniques

Reducing visual clutter from backgrounds

Question:

Im using scanned maps and photos as backgrounds for some of my diagrams, but
nodes and links are difficult to see in front of them. How can I improve object
visibility?

Answer:

Open a copy of the map or photo in an image processing program such as

PhotoShop or Paint Shop Pro. Adjust brightness and contrast to tone down the
images colors. Often, increasing brightness and decreasing contrast works, but
this will depend on the particular image. Save the image under a different name.
Then in your netViz diagram, Diagram / Background / Select... to import the altered
background image.
Its also helpful to assign darker colors to node types and link types so they contrast with backgrounds.

Diagram with background image as originally scanned

Effect of altering background images brightness and contrast

67

Guide to documenting networks

Forcing sort order in the Hierarchy Browser

Question:

The Hierarchy Browser lists diagrams alphabetically by name. How can I make
it list diagrams in a different order?

Answer:

Just precede diagram names with letters or numbers that reflect the order you
want. This technique is essential if you need to present pages of information in a
particular order (for instance, see the Temporary Workspace in the bus_proc.net
project in the Examples directory of the netViz CD-ROM).
Example: Suppose your project contains four diagrams with the following names:
Atlanta
Boston
Chicago
Denver

Now, suppose you want them to appear in the Browser in descending alphabetical
order. In the parent diagram or in the Inspector, insert a number in front of each
name, like this:
4 Atlanta
3 Boston
2 Chicago
1 Denver

netViz wont re-sort the names until youve closed and reopened the browser.
Then the Browser will show:
1 Denver
2 Chicago
3 Boston
4 Atlanta

For larger numbers of diagrams, you can use more digits (e.g., 000, 001, 002, ...),
letters (e.g., AA, AB, AC, ...) or combinations (e.g., B01, B02, B03, ...).

68

Some final words

69

70

Some final words

Critique your documentation

Question:

I did it! I documented my entire network, and it wasnt nearly as hard as I thought
it would be. What do you think of my work?

Answer:

It looks pretty good... at first glance. Now its my turn to ask you some questions:

Does your documentation meet your objectives? It has to do everything you

and your organization demand. Give yourself a gold star if your documentation
exceeds the original objectivesbecause youve discovered new ways it can
save time, save money and help you in your job.

Did you follow the General Principles? Take a moment to review your documentation in light of the Principles (listed near the beginning of this book).

Is your documentation honest? Since you (and other people) will be using it
to make decisions and take action, your documentation must accurately reflect
reality. Of necessity, documentation involves artifices, but you mustnt let
these compromise the integrity of the information. If workstation G17-7533
sits in Room 1C105, then your documentation had better show that, even if you
use simple boxes to graphically show workstations and the floor plan is a collection of guesses about room sizes.

Is your documentation eloquent? It must tell you everything you need to

know. Moreover, it must be designed so that you dont need to dig too deeply
to find any fact.

Is your name on the documentation? Take pride in your work, and offer users a real person to which they can direct their questions and comments. Put
your nameand the names of all contributorsin a prominent place. Provide
your phone number or e-mail address.

Is your documentation dated? If you (and other users) dont know when it
was created and last revised, the documentation is immediately suspect.

After your documentation has been circulating for a while...

What do users say about your documentation? Welcome their comments.

Use their suggestions to improve the documentation, so it is clearer, easier to
use and provides even more information.

71

Guide to documenting networks

The end... or is it?

Question:

Well, Ive run out of questions. Do you have any parting comments?

Answer:

Of course. (You didnt think I was finished talking about this stuff yet, did you?)

Now that you have documentation, use the hell out of it. This may be difficult at firstyou could have the urge to charge off to the equipment room or a
users office at the first hint of trouble. Now you can take a relaxing deep
breath and use your documentation to collect some facts about possible problem areas. You may still go charging off, but at least youll know what you
should find when you get there.

Load a copy of your documentation into a laptop computer.* Take the

laptop with you on reconnaissance missions. Take it on the road to work on
network performance issues. Take it to meetings to make a case for new equipment. Take it home so the boss will think youre working all night.
*There are four ways to do this:
1) Use the free Viewer program included on the netViz CD-ROM.
2) Purchase an additional copy of netViz for the laptop. (Tip: Make the traveling project and
catalog files read-only, so they cant be changed; make updates only to the original files.)
3) Output the original project in HTML format, then use a Web browser to view the (essentially
read-only) documentation on the laptop.
4) Web publish the project, then access it through your organizations Web server.

72

Implement change control. Your documentation wont be much good if it

gets out of date. It may take formal policies, it will certainly need strict procedures and will probably involve occasional arm-twisting... but ya gotta do it!
While it took perseverance to build your documentation, it will take discipline
to maintain it. See the Change control topic for suggestions.

Some final words

73

WANTED:
Your netViz tips and techniques
You can help other netViz users get the most out of this extraordinary network documentation
program. Techniques like the ones in this book can save time and produce better, more usable
documentation. So if youve invented a cool trick, send it in... I just might put it in future editions
of this book.
When you submit your tips and techniques, I need to know:
Your name
Your organization
Your address
Your phone number
Your e-mail address
Your tip or technique. WARNING: Do not attempt the extremely
dangerous task of stating your tip in question and answer format.
Leave that to highly-trained professionals (namely, me).
E-mail your submission to:
[email protected]
or mail it to:
Dr. Diagram
netViz Corp.
9210 Corporate Blvd., Suite 150
Rockville, MD 20850 U.S.A.

74

Thank you!