Today, we’re going to talk about… documentation. Okay, let out that sigh. Now take a deep breath, and give it a chance. It is not the sexiest topic in the IT world, but it happens to be one of the most critical. Mapping your work will provide ongoing direction for your administration and development. For example, someone who takes your place as you move up the ladder may need guidance on just how a certain process is supposed to work. And new hires may need help in order to get up to speed as quickly as possible.

Mapping your work
Creating documentation is not a secret process or one that entails investing in premium-priced tools. It is simply capturing the details of your LAN, WAN, and incoming and outgoing technical services (Internet access, DNS, SMTP and POP, etc.), along with information about the operations of the department, and then putting them into a manual format. Consider this: If a bus were to hit you tomorrow, would your department be able to bring in a knowledgeable administrator who could review your documentation and ensure ongoing services without interruption? For many admins, that answer is “maybe,” or even worse, “no”.

There are two levels of documentation in IT:

  • Administration operations
  • Special projects

Administration operations include a map of your network, server configurations, desktop configurations, help desk policy and process, and your staff responsibilities. Special projects can serve as a catchall for development projects and programming that may not be a part of your day-to-day IT operations.

Administration operations documentation in action
Let’s get started with the day-to-day basics. To illustrate, we’ll look at the “New Company” IT department. New Company’s network administrator, John, has three staff members, 12 servers, and 125 desktops. Additionally, he has Internet and DNS managed by a regional Internet service provider, and his network is part of a larger Wide Area Network (WAN).

On his first day on the job with New Company, John can’t seem to find any documentation to identify T1 and ISDN circuits. There is no report detailing the phone lines and hunt groups in the telecom system, nor is there a diagram of the LAN/WAN. John is in trouble. John’s staff pulls together what they have committed to memory and various e-mails with the parent firm running the WAN. John starts the documentation process.

After gathering the various pieces of required data, John creates a spreadsheet containing the New Company IP scheme. This scheme details the IP range reserved for their portion of the WAN, which includes the desktop, printer, server, and router IP ranges. Following a conversation with the WAN architect at the parent firm, John constructs a visual diagram of the LAN and WAN. This diagram includes incoming and outgoing services through the local firewalls, as well as those services (ISP and telecom) provided external to the WAN.

During the documentation project, John discovers that New Company has been paying for unused phone lines lost in unknown hunt groups. By constructing a document that listed all the main voice and data lines, then consolidating hunt group numbers under them, the unnecessary lines are cancelled, saving the company hundreds of dollars monthly.

A special project emerges
Because of the efforts of the operations documentation process, the IT department has a better understanding of the system and is able to focus its efforts in other areas. This newfound knowledge of the system also inspires a project. John’s staff proposes that IT construct its own custom database to maintain the data from the operations documentation, as well as to provide a desktop-level interface for employees to request support. The tech support staff agrees to pitch in to create an additional hardware and software inventory section.

Documenting your special projects can be a sticky issue because it raises the question, “Just what do I need to document?” Well, it is best to err on the side of over-documentation. Fortunately for John, he knows the value of proper documentation.

Step one
John and his crew proceeded with the project, using a model documentation method. They started by writing a document clearly specifying the purpose of the database, what platform was being used, and who it would serve. After crafting this summary, they began sketching out on paper the tables, table relationships, and various queries and reports, as well as the varying levels of permissions. They also sketched out their data entry forms and documented specifications for the Web page they planned to create on the company intranet to offer a data entry point for help desk requests. In performing this written procedure, they created a general map that a new set of IT staff could work from to reproduce the same basic database again.

Step two
The critical documentation step was next. As John’s crew began constructing the database, they created an index to every table, query, report, and permission:

  • Each table index detailed the proper field names, their corresponding syntax in the table file (First Name = f_name, etc.), and relationships to other tables (e.g., key IDs).
  • Each query index included the Structured Query Language used to create the query and identified the report it was associated with.
  • Each report index listed the query or queries it was related to and the users who were to use the report.
  • Each form index showed which table the form was attached to for field lookups, and so on. In addition, the team identified the Web page form and code used to connect to the database.
  • Each permission index identified not only what type of access a user or group received (read, write, etc.), but also which permissions were specific to tables, reports, and so forth.

Finally, the group printed copies of any additional custom scripting or code (e.g., Perl script for processing the form entry into the database). They also used excess comments on the script printout to assist in any possible later modifications.

Additional thoughts
As you can see, documentation projects can spur ideas. You can document your backup scheme, describe your administrative policies, get permission lists off servers, and lay out your cable cabinet (including hubs, switches and routers). The possibilities are endless. Although documentation is not always a pleasurable experience, if you get into a jam and start looking for the data you desperately need, you will be glad you or someone else took the time to write it down.
Do you think the documentation process is a worthwhile endeavor? Do you have any suggestions for making documentation easier to create and use? Post a comment at the bottom of the page or send the editor an e-mail.