Before you start writing, you must first decide on the type of manual. Each type of manual has a different set of audience, purpose and an objective.
If the reader is trying to learn the application, then you need to write a tutorial. If the user is already using the application and just wants some information, then the user is looking out for a reference manual. If the user is just upgraded the application, then the user is looking out for a release notes, to get the updates.
Documentation in a software industry can be broadly classified into two groups namely
Product documentation is describing the delivered software product. Product documentation includes two types of documentation set namely:
Users of the software product are not all the same. As technical writers we must structure the content for different tasks and expertise levels. I think it is not necessary for me to explain end user and system administrator. I will be using these terms frequently.
The user documentation set includes
If the reader is trying to learn the application, then you need to write a tutorial. If the user is already using the application and just wants some information, then the user is looking out for a reference manual. If the user is just upgraded the application, then the user is looking out for a release notes, to get the updates.
Documentation in a software industry can be broadly classified into two groups namely
- Process documentation
- Product documentation
It is very important
to manage the process for an effective management of the company. A software
development process involves a lot of cognitive task rather than physical task;
the only way of visibility is attained through technical documentation. Process
documents include the following:
- Reports
- Mails and messages
- Standards documents
- Planning and estimation
- Scheduling
Product documentation is describing the delivered software product. Product documentation includes two types of documentation set namely:
- User documentation set: A set of documents which tells the user how to use the product.
- System documentation set: A set of documents to cater the needs of the maintenance engineers.
Users of the software product are not all the same. As technical writers we must structure the content for different tasks and expertise levels. I think it is not necessary for me to explain end user and system administrator. I will be using these terms frequently.
The user documentation set includes
- Functional Specification Document
- Installation Guide
- Quick Start Guide
- User Manual
- Reference manual
- Administration guide
- Release notes
Functional Specification Document outlines the behavior of the application. The documentation typically describes what is needed by the system user as well as requested properties of inputs and outputs. This document does not describe the internal architecture of the application. It just describes the interaction between the user and the software application.
Installation Guide is for the system administrators. It provides the complete details and the step-by-step instructions to install the application. It contains the complete list of the hardware and the software requirements to install the application. It also explains the configuration changes and the system settings to be changed prior or post installation.
Quick Start Guide aims to provide the overview of the application. It mainly explains the menus, sub-menus, and navigation option etc of the Graphical user interface (GUI)
User manual is to assist the user to use the application. It is also commonly called manual. It explains the application in a language that a non-technical user can understand.
Reference manual is for the experienced users. It describes about the features and its usage. A reference manual provides the complete list of error message and its recovery procedures.
Administration guide is for the system administrator for installing maintaining and managing the application. If hardware is involved, it explains the administrator’s task in maintaining the application.
Release note is a document distributed with software product, often when the product is still in the development or test state (e.g., a beta release). For products that have already been in use by clients, the release note is a supplementary document that is delivered to the customer when a bug is fixed or an enhancement is made to the product.
System Documentation Set
System Documentation includes all the documents right from the requirement specification to the final acceptance plan. Documents describing the design, implementation and testing of a system are essential if the program is to be understood and maintained.
Installation Guide is for the system administrators. It provides the complete details and the step-by-step instructions to install the application. It contains the complete list of the hardware and the software requirements to install the application. It also explains the configuration changes and the system settings to be changed prior or post installation.
Quick Start Guide aims to provide the overview of the application. It mainly explains the menus, sub-menus, and navigation option etc of the Graphical user interface (GUI)
User manual is to assist the user to use the application. It is also commonly called manual. It explains the application in a language that a non-technical user can understand.
Reference manual is for the experienced users. It describes about the features and its usage. A reference manual provides the complete list of error message and its recovery procedures.
Administration guide is for the system administrator for installing maintaining and managing the application. If hardware is involved, it explains the administrator’s task in maintaining the application.
Release note is a document distributed with software product, often when the product is still in the development or test state (e.g., a beta release). For products that have already been in use by clients, the release note is a supplementary document that is delivered to the customer when a bug is fixed or an enhancement is made to the product.
System Documentation Set
System Documentation includes all the documents right from the requirement specification to the final acceptance plan. Documents describing the design, implementation and testing of a system are essential if the program is to be understood and maintained.
No comments:
Post a Comment