Documentation Standards

As network administrators begin to write lots of scripts, it rapidly becomes apparent that there is a need for standards. It is common for large companies to maintain a collection of “enterprise scripts” that have been tested, and approved for use as network tools. To ensure these scripts can be readily maintained, modified, and debugged, proper documentation must be included with the script. The following are suggestions for information to include with scripts.

Header Information section

The following items should be considered for inclusion in the header of a script.

1.      Script name

2.      Script writer

3.      Date the script was written

4.      Version information

5.      Description of the purpose of the script

6.      Special requirements for use of script (command line arguments, access to Active Directory)

Reference Information Section

The following items should be documented in the Reference Information section of the script.

1.      Use of all variables

2.      Use of all constants

Worker Information Section

The following items should be documented in Worker Information section of the script.

1.      Explanation of constructions used to gather information

2.      Explanation of constructions used to configure settings

3.      Explanation of any other constructions used in the script

Sample of documentation use

' +++++++++++++++++++++++++++++++++++++++++++++++++++++

' Written by Ed Wilson, 7/13/2003

' version 1.0 basic script

' from "Microsoft Windows Scripting Self-Paced Learning Guide"

' version 1.1 -- added additional documentation, 1/14/2003

' Key concepts are listed below:

 

' This script displays various Computer Names by reading

' the registry

' ++++++++++++++++++++++++++++++++++++++++++++++++++++++

Option Explicit    

On Error Resume Next

                    

Dim objShell ' holds connection to wscript.shell

Dim regActiveComputerName ' holds registry string for

                                   'active computer name

Dim regComputerName ' holds registry string for computer name

Dim regHostname ' holds registry string for hostname

Dim ActiveComputerName ' holds value found in registry

Dim ComputerName ' holds value found in registry

Dim Hostname 'holds value found in registry

 

 

regActiveComputerName = "HKLM\SYSTEM\CurrentControlSet" &_

   "\Control\ComputerName\ActiveComputerName\ComputerName"

regComputerName = "HKLM\SYSTEM\CurrentControlSet\Control" &_

   "\ComputerName\ComputerName\ComputerName"

regHostname = "HKLM\SYSTEM\CurrentControlSet\Services" &_

   "\Tcpip\Parameters\Hostname"

 

 

Set objShell = WScript.CreateObject("WScript.Shell")

Set objFileSystem = CreateObject("Scripting.FileSystemObject")

 

ActiveComputerName = objShell.RegRead(regActiveComputerName)

ComputerName = objShell.RegRead(regComputerName)

Hostname = objShell.RegRead(regHostname)

 

 

WScript.Echo activecomputername & " is active computer name"

WScript.Echo ComputerName & " is computer name"

WScript.Echo Hostname & " is host name"

Home Up

© Copyright 2004, Ed Wilson All Rights Reserved.