Developing Documentation During System Development by Narain Balchandani

Developing Documentation During System Development
by: Narain Balchandani

System documentation and user documentation are the two types of documents. System documentation is required for better understanding and maintenance of the application software. User documentation is designed to help the user operate the system. A good-quality document requires designing the documents, writing and editing the text, and testing them, and hence takes longer time for documentation. Lower-quality documentation can be produced faster. Nowadays online documentation is becoming more important compared to traditional paper-based manuals. Users are more familiar with paper-based documents and these are simpler to use. Although online documents require people to be familiar with additional software commands, searching for information is easier in online documents. These also enable the users to interact with the document.

There are mainly three types of user documentation: reference documents, procedure manuals and tutorials. Reference documents are used when the user needs to learn how to perform a specific function. Procedure manuals describe how to perform business tasks. Tutorials teach people how to use major components of the system.

Introduction

There are two types of documents.

System documentation is intended to help programmers and systems analysts understand the application software and enable them to build it or maintain it after the system is installed. System documentation is a by-product of the system analysis and design process, and is created as the project unfolds.

Each step and phase produce documents that are essential in understanding how the system is built or is to be built, and these documents are stored in the project binder(s).

User documentation (such as user’s manuals, training manuals and online help systems) is designed to help the user operate the system. Although most project teams expect users to have received training and read the user’s manuals before operating the system, unfortunately this is not always the case. It is more common today – especially in the case of commercial software packages for microcomputers – for users to begin the software without training or reading the user’s manual.

User documentation is often left until the end of the project, which is a dangerous strategy. Developing a good documentation takes longer than many people expect because it requires much more than simply writing a few pages.

Producing documentation requires designing the documents (whether paper or online), writing the text, editing them and testing them. For good-quality documentation, this process usually takes about 3 hours per paper page (single-spaced) for paper-based documentation or 2 hours per screen for online documentation.

Thus, a “simple” set of documentation such as a 20-page user’s manual and a set of 20 help screens take 100 hours. Of course, lower-quality documentation can be produced faster.

The time required to develop and test user documentation should be built into the project plan. Most organizations plan for documentation development to start once the interface design and program specifications are complete. The initial draft of documentation is usually scheduled for completion immediately after the unit tests are complete.

This reduces – but does not eliminate – the need for the documentation to be tested and revised before the acceptance tests is started.

Although paper-based manuals are still significant, online documentation is becoming more important. Paper-based documentation is simpler to use because it is more familiar to users, especially novices who have less computer experience; online documentation requires the users to learn one more set of commands. Paper-based documentation is also easier to flip through to gain a general understanding of its organization and topics, and can be used far away from the computer itself.

There are four key strengths of online documentation that all but guarantee that it will be the dominant format form for the next century. First, searching for information is often simpler (provided the help search index is well designed). The user can type in a variety of keywords to view information instantaneously, rather than having to search through the index or table of contents in a paper document. Second, the same information can be presented several times in many different formats, so that the user can find and read the information in the most informative way.

Third, online documentation enables the users to interact with the documentation. For example, it is possible to use links or “tool tips” (i.e., pop-up text) to explain unfamiliar terms, and programmers can write “show me” routines that demonstrate on the screen exactly what buttons to click and text to type. Finally, online documentation is significantly less expensive to distribute and keep up-to-date than paper documentation.

Types of Documentation

There are fundamentally three different types of user documentation: reference documents, procedure manuals and tutorials. Reference documents (also called the help system) are designed to be used when the user needs to learn how to perform a specific function (e.g., printing a monthly report, taking a customer order). Typically, people read reference information only after they have tried and failed to perform the function. Writing reference documentation requires special care because users are often impatient or frustrated when they begin to read them.

Procedure manuals describe how to perform business tasks (e.g., printing a monthly report, taking a customer order). Each item in the procedures manually guides the user through a task that requires several functions or steps in the system. Therefore, each entry is typically much longer than an entry in a reference document.

Tutorials teach people how to use major components of the system (e.g., an introduction to the basic operations of the system). Each entry in the tutorial is typically longer than the entities in procedure manuals and the entities are usually designed to be read in sequence, whereas entries in reference documents and procedure manuals are designed to be read individually.

Regardless of the type of user documentation, the overall process for developing it is similar to the process of developing interfaces. The developer first designs the general structure for the documentation and then develops the individual components within it.

Documentation and managing the documentation in company’s Intranet are critical for a company, and the resource spent on it is worthwhile. For more info on these topics and training refer to Business Analysis & Data Modeling Training Bangalore

About The Author

Narain Balchandani, Director of Integrated Quality Training Institute, Bangalore, has more than 14 years of experience in the field of teaching. His favourite subjects include Business Analysis, Data Modelling, writing, UML and so on. IQTI offers training in these topics. For more info, refer to http://www.iqtiedu.com

The author invites you to visit:
http://www.iqtiedu.com