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
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
Categories: LessonsTechnical writing
Navigation menu
Not logged in
Talk
Contributions
Create account
Log in
ResourceDiscuss
ReadEditEdit sourceView historySearch
Search Wikiversity
Main Page
Browse
Recent changes
Guided tours
Random
Help
Donate
Community
Portal
Colloquium
News
Projects
Sandbox
Help desk
Tools
What links here
Related changes
Special pages
Permanent link
Page information
Cite this page
Wikimedia projects
Commons
Wikibooks
Wikipedia
Wiktionary
Wikiquote
Wikisource
Wikinews
Wikispecies
Wikivoyage
Meta-Wiki
Outreach
MediaWiki
Wikimania
Print/export
Create a book
Download as PDF
Printable version
In other languages
Add links
This page was last edited on 20 October 2020, at 17:38.
Text is available under the Creative Commons Attribution-ShareAlike License;
additional terms m
