Technical Writing Types of User Documentation

Generally, documentation is divided into two main areas.

• Process Documents guide the development, testing, maintenance and improvement of systems. They are used by managers, engineers, testers, and marketing professionals. These documents use technical terms and industry specific jargon.

• User Documents give customers the information they need to use the product. They are primarily teaching materials which include some technical explanation. They use everyday terms in place of technical jargon, making it easier for the novice or outsider to understand the system.

Process Documents

For large software projects, technical writers start preparing the documentation even before development starts. Technical writers have to produce different types of documents during the SDLC such as:

• test plans
• design specifications
• project plans

Following are the process documents that provide information related to the development and maintenance of the system:

• Estimates, plans and schedules: The managers usually prepare this type of product documents that describe how to manage and control the software.
• Reports: These documents report on resource use during the development process.
• Standards: These documents outline how to implement the process needs.
• Working Papers: These are the most important technical communication documents of a project. Working papers record the thoughts and ideas of the developers working on the project. They explain the underlying principle behind the implementation of the design. Working Papers also describe implementation strategies.
• Electronic mail messages and Memos: These documents contain communication between managers and software developers. These are of primary interest to the software historians.

Initiation Phase Indented line Project Proposal Marketing Study Feasibility Analysis

Analysis and Planning Phase

• User Requirements
• Functional Specification
• Design Documents
• Project Plan
• Work Breakdown Structure
• Configuration Management
• Test Plan
• Delivery Plan
• User Training Plan
• Acceptance Tests

Development Phase

• Detailed Design
• Code Comments
• Test Cases

Testing and Integration Phase

• white box testing
• black box testing

top down integration and bottom up integration phase

Delivery Phase

• Installation and Maintenance Manuals (See User Documentation below)
• Training Delivery
• Troubleshooting and Issue Tracking

Maintenance Phase

• Upgrades and Patches
• Troubleshooting and Knowledge Base

Improvement Phase

• Project Accounting
• Lessons Learned

Product Documents

Product documentation offers comprehensive description and information on the product. The product documentation has a relatively long life compared to the process documentation. The technical writers start preparing the product documentation while the product is being developed. Writing the product documentation and developing the product is a simultaneous process. The product documentation can be categorized into:

• User Documentation: The user-documentation is written for the end-users. It contains elaborate information on how to use a particular product.
• System Documentation: It is primarily intended for the system and maintenance engineers.

User Documentation

The technical writer structures the documentation so that it caters to different user tasks and meets the requirements of users with varied experience and expertise. The technical writer must be able to differentiate between the users and system administrators.

• End-users employ the software to get their job done. The user can use the software for writing a book, for managing their insurance policies, or for flying an aircraft. The end-users are not interested in learning the intricate details of the software. They only want to know how they can employ the software for performing a particular task.
• It is the job of the system administrators to manage the software for the end-users. The system administrators's job can be manifold; they can work as a network manager in case the system requires a network of workstations, as an operator if it's a huge mainframe system, or as a technical expert who fixes software problems for the end-users.

Types of User Documents

Technical writers prepare documents for different types of users. Typically, there are five basic types of user documents:

• Description Document - The functional description document provides information on the system requirements and the services offered. This document should offer a detailed overview of the software. The end-users should be able to decide whether this is the software they are looking for after going through the introductory manual.
• Installation - The system installation document is meant for the system administrators; this document should provide information on how to install the system. The system installation document should contain a description of the system files and the hardware configuration required. It should also offer detailed information on how to operate the system, how the configuration dependent files should be customized and how to establish the permanent files.
• Configuration - The system configuration document is meant for the system administrators or users. This document provides information on how to configure the system or the software for end-use. You can combine this document with the system installation document depending upon the requirement and the volume of information.
• User Manual - The user manual should introduce the audience to that particular system. It should outline the normal functions of the system and should provide instructions on how to get started and how to use the various applications. The instructions should be further illustrated with examples.
• Systems Reference - The system reference documentation should provide information on the system facilities, how to use those facilities, list of error messages and how to recover from errors. The system reference manual should be written in a descriptive style.