Technical writing/Types of User Documentation

Generally, documentation is divided into two main areas.

Process Documentation guides 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.

Product Documentation gives 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 Documentation

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 document that describes how to manage and control the software.

Reports: These documents report on resource use during the development process.

Standards and conventions: 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 (WBS)

Configuration Management

Test Plan

Delivery Plan

User Training Plan

Acceptance Tests

Development Phase

Detailed Design

Code Comments

Test Cases
Version Control Records

Integration & Testing Phase (I&T)

Top-down Testing
Bottom-up Testing
Mixed ("Sandwich") Testing
Big-bang, Risky-hardest, etc.

Delivery Phase

Installation and Maintenance Manuals (See Product Documentation below)

Training Delivery

Troubleshooting and Issue Tracking
Release Notes (depending on the methodology)

Maintenance Phase

Updates and Patches
Release Notes

Troubleshooting and Knowledge Base

Improvement Phase

Project Accounting

Lessons Learned

Product Documentation

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 end-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.

System administrators manage the software for the end-users. The system administrator'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 four basic types of user documents:

Features Description - The functional description lists features, describes complex GUIs and provides information on the services offered by the system. 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.
Administrator Manual
- System Requirements - minimum hardware requirements to use the software i.e. cpu speed, number of cores, memory requirements and any software environment or application prerequisites.
- 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.
System References - The system reference documentation should provide information on the system facilities, how to use those facilities, a list of error messages and how to recover from errors. The system reference manual should be written in a descriptive style. It holds detailed information for the most advanced or highly technical users.

back to Technical Writing Level 2