DOCUMENTATION

Documentation and Importance of Documentation

Documentation is one of the system which is used to communicate, instruct and record the information for any reference or operational purpose. They are very useful for representing the formal flow of the present system. With the help of documentation it is very easy to track the flow of the system's progress and they working of the system can be expalined very easily.

It helps to provide the clear description of the work done so far. It is essential that the documents prepared must be updated on regular basis this will help to trace the progress of work easily. With appropriate and good documentation it is very easy to understand the how aspects of the system will work for the company where the system is to installed. It is also help to understand the type of data which will be inputted in the system and how the output can be produced.

After the system is installed, and if in case the system is not working properly it will be very easy for the administrator to understand the flow of data in the system with documentation which will help him/ her to correct the flaws and get the system working in no time.

Uses of Documentation

• It facilitates effective communication regarding the system between the technical and the non technical users.
• It is very useful in training new users. With a Good documentation new users can easily get acquainted with the flow of the systems.
• Documentation also helps the users to solve problems like trouble shooting even a non technical user can fix the problems.
• It plays a significant role in evaluation process.
• It not only helps to exercise a better control over the internal working of the firm, but it also external as well especially during audit.
• Documentations can help the manager to take better financial decisions of the organization.

Characteristics

What the characteristics of good system documentation are is difficult to decide. Some desirable characteristics are described below:

Created for intended audience

The documentation should be created for the intended audience. While it may be appropriate for a "Management overview" to be created for non-technical people, most system documentation will be used by System Administrators and other technical people as an important reference. System documentation should provide sufficient technical detail.

Specific

The system documentation should describe the specific implementation of a given system rather than provide generic documentation.

Relationship with other documentation

System documentation should be reasonably self contained; however it will often be a component of a wider collection of documentation and it is reasonable for it to reference other documents. There is little value in duplicating information from Vendor's manuals.

Up to date

The documentation needs to be up to date, but does not necessarily have to be recent. If the system has remained completely unchanged for a long period of time, the documentation can remain unchanged for the same period of time. It is important that when systems are changed documentation is updated to reflect the changes and this should be part of any change control procedures.

Sufficiently comprehensive

Documentation needs to be sufficiently comprehensive to for fill its purpose.

Accessible

The documentation must be held in a location and format that makes it accessible. It is obviously unacceptable to have the only copy of a system's documentation held on a drive that has failed or on the system itself should it fail.
It is very desirable to hold the documentation in a universal standard format that does not require access to a particular word processor; ASCII text may be most suitable.

Secure

Because system documentation could be useful to troublemakers, thought may need to be given to controlling access to the documentation.

Requirements

The question of what is the purpose of system documentation is difficult to answer. Below are some possible uses of system documentation.

Introduction / overview

System documentation can provide an introduction and overview of systems. New Administrators, contractors and other staff may need to familiarise themselves with a system; the first thing that will be requested is any system documentation. To avoid staff having to waste time discovering the purpose of a system, how it is configured etc system documentation should provide an Introduction.

Disaster Recovery

Many systems are supported by disaster recovery arrangements, but even in such circumstances, the recovery can still fail. There may be a need to re-build a system from scratch at least to the point where a normal restore from backup can be done. To make a rebuild possible it will be necessary to have documentation that provides answers to the configuration choices. For example it is important to re-build the system with the correct size of file systems to avoid trying to restore data to a file system that has been made too small. In some circumstances certain parameters can be difficult to change at a later date. When rebuilding a system it may be important to configure networking with the original parameters both to avoid conflicts with other systems on the network and because these may be difficult to change subsequently.

OS or Application re-load

Even when a disaster has not occurred, there may be times when it is necessary to reload an Operating System or Application; this can either be as part of a major version upgrade or a drastic step necessary to solve problems. In such circumstances it is important to know how an OS or Application has been configured.

Trouble shooting aid

The benefits of good system documentation, when trouble shooting, are fairly obvious. A comprehensive description of how a system should be configured and should behave can be invaluable when configuration information has become corrupted, when services have failed, or components have failed.
Good system documentation will include a description of the physical hardware and its physical configuration, which can avoid the need to shutdown a system in order to examine items such as jumper settings.

Planning tool

When planning changes or upgrades it will be necessary to assess the impact of changes on existing systems. A good understanding of existing systems is necessary for assessing the impact of any changes and for this good system documentation is required.

Other

System documentation can be used for many purposes including Auditing, Inventory, Maintenance, etc. The documentation of individual systems forms an important component of the overall network documentation.

Automating the creation of system documentation

Most operating systems include tools to report important system information and often the output from such tools can be re-directed to a file; this provides a means of automating the creation of system documentation.
Many Administrators have neither the time nor inclination to produce System Documentation and given the importance of keeping such documentation current, automation of the creation of system documentation is very desirable.
There are limitations to the extent to which system documentation can be automated. The following cannot be documented automatically:

• Textual descriptions that Administrators may create.
• Hardware configuration items that cannot be detected through software (perhaps such as which slot on a bus a card occupies or how jumpers are set).
• Other items that cannot be detected through software such as serial numbers, the physical location of a system etc.

The documentation of items that cannot be documented automatically can be facilitated by such means as having standard template documents and creating such documentation when systems are first installed. Fortunately this kind of documentation is less susceptible to change and is often less critical. It may be useful to create a simple file in a standard location (perhaps root) on systems that contains "external" information such as serial numbers, asset numbers etc.
Most Operating Systems have tools for automating their deployment (e.g. unattend.txt for NT, JumpStart for Solaris, Kickstart for Redhat Linux etc). Although these tools are primarily intended for deploying large numbers of systems they can be used for individual systems. While the configuration scripts used in these tools are not very readable, they are in text form, and can be read by technical staff. Such scripts offer the great advantage that a system is documented in an unambiguous way that guarantees that the system can be rebuilt exactly the same way it was first built.
For most systems it should be possible to create a simple script (or batch file) that uses several system tools to report system information and out put the results to a file. The use of such tools together with simple print commands (e.g. echo "line of text") can readily produce a useful document. It should be possible to adapt such scripts to produce the documentation required in terms of content and level of detail etc.
If standard tools do not provide sufficient information, there are many third party tools and free tools that can be used, however the potential problems of using additional tools, rather than just "built-in" tools, has to be weighed against the advantages. Alternative scripting languages (such a Perl) may provide additional benefits.