SOFTWARE DOCUMENTATION

STRATEG IES FOR TECHNICAL WRIT ERS

Version 3.01.01.09.27
Edward B. Toupin

All trademarks mentioned throughout this publication are property of their

respective owners.
Electronic Publishing by
Online Books Inc., PO Box 268, Mt. Vernon, VA 22121
http://www.onlinebooksinc.com, editor@onlinebooksinc.com.
Copyright 2001, Edward B. Toupin. All rights reserved.
Manufactured in the United States of America.
No part of this publication may be reproduced, stored in a retrieval system,
or transmitted in any form or by any means, electronic, mechanical,
recording, or otherwise without the prior written permission of Edward B.
Toupin.
Provide your feedback at http://www.delphi.com/onlinebooksinc/.

Table of Contents
List of Figures..............................................................................................................vii
About The Author .........................................................................................................ix
Acknowledgements ......................................................................................................xi
Preface.........................................................................................................................xiii
1. Introduction ..............................................................................................................1
2. Roles .........................................................................................................................3
2.1 Management ...................................................................................................................3
Publishing Manager ........................................................................................................3
Project Manager..............................................................................................................3
Quality Manager..............................................................................................................4
2.2 Production.......................................................................................................................4
Development Editor.........................................................................................................4
Production Editor.............................................................................................................4
2.3 Development...................................................................................................................5
Technical Editor (SME) ...................................................................................................5
Copy Editor .....................................................................................................................5
Technical Writer ..............................................................................................................5
2.4 Additional Roles ..............................................................................................................5

3. Software Processes .................................................................................................7

3.1 Pre-Development ............................................................................................................7
3.2 Project Management .......................................................................................................8
3.3 Design.............................................................................................................................9
3.4 Development.................................................................................................................10
3.5 Post-Development.........................................................................................................11
3.6 Integral Processes ........................................................................................................11

4. Software Process Documentation ........................................................................13

4.1 Requirements Analysis..................................................................................................13
4.2 Functional Specification ................................................................................................13
4.3 Customer Proposal .......................................................................................................14
4.4 Software Design Document...........................................................................................15
4.5 Feature Update Document ............................................................................................16

5. Testing Documentation .........................................................................................17

5.1 Formative Test ..............................................................................................................17
5.2 Build Test ......................................................................................................................18
5.3 Unit Test........................................................................................................................18
5.4 System Test ..................................................................................................................18

5.5 Validation Test ..............................................................................................................18

5.6 User Acceptance Tests .................................................................................................19
5.7 User Feedback..............................................................................................................19

6. Software Configuration Management...................................................................21

6.1 Software Configuration Management ............................................................................21
6.2 SCM for the Technical Writer ........................................................................................21
6.3 Source Code Versioning and Tracking ..........................................................................22
6.4 Installation Builds ..........................................................................................................22
6.5 QA.................................................................................................................................23
6.6 Bug Tracking and Resolution ........................................................................................23
6.7 Packaging .....................................................................................................................24
6.8 Deployment...................................................................................................................24
6.9 Customer and Technical Support ..................................................................................24
6.10 Procedure Management ............................................................................................25

7. Software Control and Tracking .............................................................................27

7.1 Internal Weekly Project Review.....................................................................................27
7.2 Monthly Meetings ..........................................................................................................27
7.3 Library Standards and Version Control..........................................................................28
7.4 Expectation Management..............................................................................................28

8. Documentation Development Process.................................................................29

8.1 Library Standards and Version Control..........................................................................29
Working Library .............................................................................................................30
Master Library ...............................................................................................................30
Releases .......................................................................................................................30
8.2 Software Development Team ........................................................................................30
8.3 Documentation Team ....................................................................................................30
8.4 Marketing Documentation .............................................................................................31
8.5 Documentation Flow .....................................................................................................32

9. Documentation Change Management ..................................................................33

9.1 Change Phases.............................................................................................................33
Original Requirements...................................................................................................33
Development Phase Requirement Submission..............................................................33
Production Requirement Submission ............................................................................34
Post-Production Requirement Submission ....................................................................34
9.2 Change Identification ....................................................................................................34
9.3 Change Management Process ......................................................................................34
9.4 Managing the Flow of Information .................................................................................35

10. Quality Management ..............................................................................................37

10.1 Procedures................................................................................................................37
10.2 Rapid Development...................................................................................................37
10.3 Quality Assurance Mechanism ..................................................................................38
Internal Weekly Project Review.....................................................................................38
Monthly Meetings ..........................................................................................................38
10.4 Expectation Management..........................................................................................39
10.5 Risk Assessment.......................................................................................................39

Resolution .....................................................................................................................39
Design Phase Issues.....................................................................................................39
Development Phase Issues...........................................................................................40
Production Phase Issues...............................................................................................40
Post-Production Phase Issues ......................................................................................40

11. Documentation Analysis .......................................................................................41

11.1
11.2
11.3
11.4
11.5

The Brief ...................................................................................................................41

Researching the Document .......................................................................................41
Audience Profile ........................................................................................................42
Task Analysis ............................................................................................................43
Product Profile...........................................................................................................44

12. Documentation Design ..........................................................................................47

12.1 Documentation Plan ..................................................................................................47
12.2 Style Guide................................................................................................................47
12.3 General Content ........................................................................................................48

13. Documentation Development................................................................................49

13.1
13.2
13.3
13.4
13.5

First Draft ..................................................................................................................49

Substantive Edit ........................................................................................................49
Technical Edit............................................................................................................50
Copy Edit ..................................................................................................................50
Final and Review.......................................................................................................50

14. Document Testing ..................................................................................................53

14.1 Formative Usability Testing .......................................................................................53
14.2 Evaluative Usability Testing.......................................................................................54
14.3 User Comments ........................................................................................................54

15. Project Management Tools....................................................................................57

15.1 Control of the Development Environment ..................................................................57
15.2 Multiple Projects ........................................................................................................57
15.3 Developing the Schedule...........................................................................................58
15.4 Estimating Page Count and Writing Hours.................................................................58
Minutes and Hours Method ...........................................................................................59
Top-Down Approach .....................................................................................................59

16. Information Management.......................................................................................61

16.1
16.2
16.3
16.4

Objectives .................................................................................................................61
Product Functions .....................................................................................................62
Application Overview.................................................................................................62
What's next?..............................................................................................................65

A1. General Links.......................................................................................................68

A2. Research Links ....................................................................................................70
A3. Tools and Software .............................................................................................71
A4. Templates.............................................................................................................73

Index ............................................................................................................................75

List of Figures
Figure 1: Roles ................................................................................................................3
Figure 2: Documentation Levels ....................................................................................29
Figure 3: Documentation Flow.......................................................................................32
Figure 4: Information Management................................................................................63

About The Author

Edward B. Toupin is a freelance consultant, writer, and published author living in Las
Vegas. He currently handles technical writing tasks for various companies in New York,
Chicago, and Denver as well as imagineers and markets feature-length and short
screenplays.
Edward provides quality Web site design, development, and marketing as well as
writing, document design and planning, and e-book publishing services. You can visit
his Web site at http://www.toupin.com or contact him at etoupin@toupin.com.

Acknowledgements
This e-book is an accumulation of notes and experience collected over the past 10
years in the software development and technical writing arenas. I want to thank all of
my clients for their feedback, patience, and successes that gave me the means to
provide this e-book for the masses.

Preface
Technical writing for the software industry is no longer just writing documentation. This
makes the design and development of software documentation one of the more difficult
tasks for all Technical Writers. To be successful, the Technical Writer must be able to
adjust quickly to a fast-paced environment and be well versed in:

Software Life Cycle,

Software Configuration Management (SCM),

Interpersonal Skills,

Process Management, and

Project Management.

Of course, standard methods taught to Technical Writers in academia don't always take
into account the varying aspects of software development. Additionally, those software
development elements taught are for the perfect software company---a company with
design documentation and available information and processes to support the Technical
Writer's work. Real-world software documentation is not straightforward and does
present challenges beyond the standard Technical Writer's expectations.
For instance, with software companies, time to market is incredibly important. In most
cases, one person devises an idea and begins developing a product. From the
prototype comes a business plan to acquire venture capital. Finally, a new company
with several employees is born. The problem is that, in all of this, no one bothered to
document what it is that the product does or how it's designed ... it sits in the mind of
one person.
Because of the volatility of technology, it's vital to the success of the company to have
its product out to its customers as soon as possible. The Technical Writer must be able
to flow with the company and help them grow...not stop the process because it doesn't
fit into the writer's process. An all too common problem for writers in today's,
unstructured, fast-paced technological environments is that they tend to slow the
release process.
The purpose of this e-book is to provide a generic approach to working with varying
software development processes and companies. Additionally, the content provides
information on writing about the mysterious non-existent product as well as how to
formalize procedures that work into, or support, the processes that may, or may not,
exist within the company. The content steps through the process of technical writing for
standard software development environments and helps the reader understand how to
adapt these processes to non-standard environments of today's software industry.
Good luck in your endeavors!

1. Introduction
One of the jobs of a documentation team is to monitor and document processes as well
as understand the needs of the internal and external customers. This is a useful task as
long as some level of processes is established within the organization. In some cases,
software companies don't support any productive processes, but usually work in an
oscillating approach to developing and deploying a product. The basic approach,
however, can be encapsulated into a standard set of processes so that you can
research and analyze all aspects of a project to meet the customers' requirements.
This e-book details the processes of software documentation development.
Additionally, it provides a way to gauge documentation quality and performance as well
as provide an understanding of the overall mechanisms for managing internal and
external software documentation. This e-book takes the reader to the next step and
provides them with the knowledge to be able to intuitively understand how to:

find information within a product's development cycle;

organize and filter relevant information;

interact with developers;

know when information is missing and fill in the blanks;

help evolve the company's processes;

become involved in the product development; and

adapt standard practices to a product's unwieldy cycle.

Software documentation is more than just writing. Software documentation involves

organization, change management, and quality management---the process becomes an
information management opportunity. Not only are you researching and writing the
documentation, but you also have to develop some means of organizing and managing
the morass of information necessary to maintaining the documents and supporting the
flow of information within the organization. You become an Information Manager!
An Information Manager has, in the past, been associated with the idea of workflow
computing. Today, with the evolution of customer relationship management (e.g., CRM,
ERP, etc.), the Information Manager's role is changing to support a contiguous flow of
information that assists in handling support centers and customer service. Information
is the key, but sometimes information is either non-existent or in varying, conflicting
forms. This is where you have to go beyond the standard Technical Writer role and
devise mechanisms and processes that not only provide you with the information you
need, but also provide support and process for the company's development
infrastructure.

2. Roles
Defining the various roles of a documentation team is important for managing
information flow. Not only does a hierarchy define the chain of command, but it also
identifies mechanisms for information exchange between the various teams. Of course,
in most cases, the documentation team consists of one or two people. This is when you
must either accept multiple roles or identify
others that will act in the role's capacity.
Each team member has a specific set of core
responsibilities and accepts additional
responsibilities to ensure the success of a
project. The following sections outline the
core responsibilities of the documentation
team to support quality relationships for a
software documentation project.

Publishing
Manager

Quality
Manager

Project Manager

Development
Editor

Production
Editor

2.1 Management
The management team provides direction
and support for the development and
production teams.
These roles are
divided in a hierarchy that separates the
amount of overall responsibility per level.

Technical
Editor

Technical Writer
I + II

Copy Editor

Figure 1: Roles

Publishing Manager
The Publishing Manager is responsible for the direction of all projects to ensure that:

they follow accepted schedules,

budgets are maintained, and

senior management is informed of project status.

This role has a view of the entire process and is able to direct individual Project
Managers to ensure that overall company goals are achieved. The Publishing
Manager reports to the Director of Software Development or the Vice President of
Engineering.

Project Manager
The Project Manager is responsible for the direction and management of an
individual project. This role is responsible for:

creating project plans,

preparing schedules, and

ensuring that all projects are within accepted standards.

Additionally, this role must ensure that each member of the project team has the
necessary resources to perform their tasks, resolves any issues that arise, and
maintains the schedule and budgetary requirements of the specific project.

Quality Manager
The Quality Manager is responsible for ensuring that projects follow quality
guidelines and that the documentation deliverables meet or exceed the quality
expectations outlined in quality management documentation. The Quality Manager
interfaces with the Project Manager for each project as well as monitors the progress
of the project. In most cases, the Project Manager takes on the role of the Quality
Manager.

2.2 Production
The production team is responsible for the design and creation of each
documentation project. This level of the hierarchy is separated by project phase to
break each project into manageable production pieces.

Development Editor
The Development Editor ensures that all team members follow project specific
requirements. This role must gather information for the project, lead the different
informational components of the project, and ensure that all deliverables are
provided at the appropriate milestones. This role must also ensure that audience,
format, and style guidelines are maintained throughout each project.
The Development Editor reports to the Project Manager and leads the Development
Staff during the design and development stages of the project. Responsibility of the
Development Editor is passed to the Production Editor when the project has
completed the initial research and development stages.

Production Editor
The Production Editor reports to the Project Manager. This role leads the production
of the project and is responsible for quality assurance during production. The editor
must ensure proper formatting, pre-press management, press management, postpress review, evaluative testing, and packaging.

2.3 Development
The development team is responsible for the actual creation of the documentation.
This team must use the designs and schedules created by the production team to
ensure timely delivery of quality product.

Technical Editor (SME)

The Technical Editor is a Subject Matter Expert (SME) and is responsible for the
review and correction of technical issues for any given document. The Technical
Editor is usually a member of the software development team. They report to their
department head, however, they are loaned to the documentation team per project.
During the loan period, the Technical Editor reports to the Development and
Production Editors, depending on the status of the project.

Copy Editor
The Copy Editor is responsible for final reviews and content management. This role
ensures that the document complies with grammatical and formatting style
guidelines. The Copy Editor reports to the Development and Production Editors,
depending on the status of the project.

Technical Writer
The Technical Writer is responsible for all writing, research, and creation of
documentation. They must follow each software project and learn the target topics
to ensure proper content development. Additionally, with the Development Editor,
the Technical Writer is responsible for the creation of documentation plans, style
guides, and notes for test plans. The Technical Writer reports to the Development
and Production Editors, depending on the status of the project.

2.4 Additional Roles

Numerous other roles within the documentation process are important for each
project, including graphics developers, customers, management, marketing,
engineers, architects, testers, and developers.
It's essential to outsource
appropriate resources during the course of each project to ensure the success of the
project.

3. Software Processes
When creating a software documentation set, it's difficult to find the information you
need if you don't know where to look. However, to know where to look, you have to
understand the basic phases of a software development process.
For those software companies that have a development process in place, your
knowledge of their process will allow you to be more efficient when researching their
products and tools. If you happen to work with a company without a solid process, the
following content provides a general template that you can overlay to determine the best
course of action.
This information is important as it will give you an idea of the different documents
assembled for each phase of a project. With this generic process, you can either create
the documents or find and use them for your software documentation.

3.1 Pre-Development
Pre-development includes a discovery or exploration stage used to generate a
Requirements Analysis Document.
This document is a stepping stone for
development and ensures that the initial customer requirements are captured and
used as a basis for the remainder of the project.
For core product development, there's not usually a customer from whom
requirements can be acquired. In such cases, the company's developers and sales
people usually take the requirement information from market research and sales
calls made.

Concept Exploration

Interview the customer.

Learn the customer's terminology and technology.

Identify ideas or needs.

Prepare a Requirements Analysis Document.

Functional Design

Formulate potential approaches.

Analyze functions.

Decompose system requirements.

Refine and finalize idea or need.

Conduct feasibility studies as necessary.

Plan system transition if product is replacing an existing product.

Develop a Functional Specification Document.

Prepare a Customer Proposal.

Perform modifications based on the customer's feedback.

Obtain sign-off from the customer.

Once the basic requirements are acquired, you have to go through the steps for
Functional Specification. A Functional Specification Document explains the various
aspects of the proposed project, however, it doesn't explain how the project will be
developed. This is more of a conceptual approach to the design and involves a
general set of solutions.
The Customer Proposal is the deliverable that contains a marketing approach to
technical design. This is where the business, sales, and technical teams merge their
information for presentation to the customer. This document usually contains
aspects of the contract, sales information, and a technical breakdown of the project.
The document also presents a proposed schedule, resource requirements, and
budgetary considerations.

3.2 Project Management

Project Management is an important aspect of every project and a part in which you
need to participate. The most important element of the process is the Software Life
Cycle Model (SLCM). There are various linear models, cyclic models, and models
for rapid development. In all cases, the model defines the way that the project will
proceed and allows you to better determine where information is readily available to
you.
Quality Management is the part of the project where the deliverables are checked for
accuracy, adherence to the original requirements, and budgetary and time
considerations. From this part of the process, you can acquire a large amount of
information, especially if you get involved with some part of the quality process. In
this way, you'll be close to the actual software and requirements to better understand
the ultimate core functionality of the project. If you're able to get involved in the
quality process, you'll know and understand the path of the product regardless of the
number of changes the product experiences in development!

Project Initiation

Identify and select SLCM.

Map development activities to SLCM.

Allocate project resources.

Establish project environment.

Plan project management.

Software Quality Management

Plan software Quality Management.

Define metrics.

Manage software quality.

Identify quality improvement needs.

Project Monitoring and Control

Analyze risks.

Perform contingency planning.

Manage the project.

Retain records.

Implement problem-reporting method.

Monitoring and controlling the development process allows a company to better

estimate risks associated with a project. For instance, in a simple case, if a
company must meet a delivery deadline, but they're behind schedule, they must
somehow compensate. In this case, risk analysis and planning allows the company
to deliver the product in a semi-finished state and provide another deliverable later.
The company must analyze the best possible paths to avoid any conflicts and, in
some situations, provide a hack just to get the product into the market.
Such hacking and contingency planning can be a nightmare for the Technical Writer.
You could end up generating a 400-page document where, in the end, only 75% of
the content is applicable and 10% of that content is inaccurate. If you're able to stay
on top of the project monitoring and control processes, you'll be ready for any
possible last minute glitches that occur with the product.

3.3 Design
The design process takes the various documents and processes discussed so far
and uses the information to create a Software Design Document. This document
contains the detailed design of the product as well as any architectural and resource
information. Additionally, as part of the design process, developers devise a
standard set of input expectations and output requirements. This information is the
basis for test data used in creating a Test Plan.

Initial

Define system architecture.

Refine and finalize idea or need.

Define interface requirements.

Prioritize and integrate software requirements.

Design

Perform architectural design.

Design interfaces and persistence mechanisms.

Select or develop algorithms.

Perform detailed design.

Create test data.

Plan integration.

Create Software Design Document.

3.4 Development
The development process involves the actual creation of the product. During each
step of development, the developer performs unit level testing to ensure that the
individual components work as expected. Once the individual components are
integrated, the code is placed into the Software Configuration Management (SCM)
process to test the product through builds and testing procedures.

Implementation

Code each module according to the Software Design Document.

Perform unit level testing.

Perform integration.

Create operating documentation.

Perform build testing.

Verification and Validation

Plan verification and validation.

Execute verification and validation tasks.

Collect and analyze data and compare to established metrics.

Plan testing and create a Test Plan.

Develop test requirements.

Execute the tests.

Testing is part of the actual development process. Its primary purpose is to ensure
that the product is bug free. However, bug free has many definitions: not crash, not

destroy data, and, the most important, function according to the original
requirements. Even if the product functions in an operating environment, if it doesn't
do what it's supposed to, then it's classified as buggy.

3.5 Post-Development
Once the product has been developed and fully tested, it's ready for packaging and
distribution. This is where your documentation comes into play for the internal staff
and for the users. You'll need to determine the best possible documentation
deliverables depending on the company's packaging and deployment.
At this point, it's important to be able to accept input from the customer using bug
tracking, feedback forms, customer service, and User Acceptance Tests. As
problems are encountered, the problem reports are presented to development and
the SCM process is used to resolve the issues.

Installation

Plan installation.

Distribute software.

Install software.

Obtain acceptance of software in operational environment.

Operation and Support

Provide technical assistance and consulting.

Maintain support request log and change management.

Maintenance

Reapply SLCM as required.

Document changes with Feature Update Document.

Retirement of Existing System

Notify user.

Conduct parallel operations.

Retire old system.

3.6 Integral Processes

There are a few other processes merged with the Software Development Process.
It's important to understand how these processes fit into the various phases of the
selected SLCM. For instance, documentation development is an ongoing process

that parallels the software project. From the previous content, you now know where
the various documents fit into the overall scheme so that you can efficiently acquire
information for the documentation.
Change Management is a process that controls how the software is changed and
what changes are applied. For example, if five customers report bugs, but only
three of the bugs are reproducible and one of those bugs is critical, it is a possibility
that the other two bugs will be placed in a slush pile for later. The three main bugs
will then be prioritized by their critical nature.

Documentation Development

Plan documentation.

Develop documentation.

Produce and distribute documentation.

Software Change Management

Plan Change Management.

Develop Change Identification.

Perform Change Control.

Perform status accounting.

Training

Plan training program.

Develop training materials.

Validate training program.

Implement training program.

Training documentation should be one of the numerous documents included into the
documentation sets. It's necessary to provide a high-level view of the product so
that a user can quickly scan the document and understand the general concepts. A
workbook format or presentation slides are of great use for this purpose!

Thank you for reading the sample of this e-book!

The remainder of this e-book can be purchased at:
http://www.toupin.com/lib_index.html