Software Documentation

Written By: Ian Sommerville Presentation By: Stephen Lopez-Couto

Discussion Topics
1. 2. 3. 4.

5.
6. 7. 8.

Introduction Documentation Requirements Process and Product Documentation Document Quality Standards Document Preparation Document Storage Conclusion

Introduction

This paper provides an overview of the

Reasons for software documentation

Types of software documentation

Ways to implement software documentation
Processes

and Good Ideas

Documentation Requirements

General requirements of all software documentation

Should provide for communication among team members Should act as an information repository to be used by maintenance engineers Should provide enough information to management to allow them to perform all program management related activities Should describe to users how to operate and administer the system

Documentation Requirements

In all software projects some amount of documentation should be created prior to any code being written

Design docs, etc.

Documentation should continue after the code has been completed

Users manuals, etc.

The two main types of documentation created are Process and Product documents

Process Documentation

Used to record and track the development process

Planning documentation Cost, Schedule, Funding tracking Schedules Standards Etc.

This documentation is created to allow for successful management of a software product

Process Documentation

Has a relatively short lifespan Only important to internal development process

Except in cases where the customer requires a view into this data

Some items, such as papers that describe design decisions should be extracted and moved into the product documentation category when they become implemented

Product Documentation

Describes the delivered product Must evolve with the development of the software product Two main categories:

System Documentation
User Documentation

Product Documentation

System Documentation

Describes how the system works, but not how to operate it Requirements Spec Architectural Design Detailed Design Commented Source Code

Examples:

Including output such as JavaDoc Including test cases

Test Plans

V&V plan and results List of Known Bugs

Product Documentation

User Documentation has two main types

End User System Administrator

In some cases these are the same people

The target audience must be well understood!

Product Documentation

There are five important areas that should be documented for a formal release of a software application

These do not necessarily each have to have their own document, but the topics should be covered thoroughly

1. 2. 3. 4. 5.

Functional Description of the Software Installation Instructions Introductory Manual Reference Manual System Administrators Guide

Document Quality

Providing thorough and professional documentation is important for any size product development team

The problem is that many software professionals lack the writing skills to create professional level documents

Document Structure

All documents for a given product should have a similar structure

A good reason for product standards

The IEEE Standard for User Documentation lists such a structure

It is a superset of what most documents need

1. 2.

3.
4.

The authors best practices are: Put a cover page on all documents Divide documents into chapters with sections and subsections Add an index if there is lots of reference information Add a glossary to define ambiguous terms

Standards
Standards play an important role in the development, maintenance and usefulness of documentation Standards can act as a basis for quality documentation

But are not good enough on their own

Usually

define high level content and organization

There are three types of documentation standards ->

1.Process Standards
Define the approach that is to be used when creating the documentation Dont actually define any of the content of the documents
Draft Peer Reviews Revise Check

2. Product Standards

Goal is to have all documents created for a specific product attain a consistent structure and appearance

Can be based on organizational or contractually required standards

1.

Four main types:

Documentation Identification Standards Document Structure Standards Document Presentation Standards Document Update Standards

2.
3. 4.

2. Product Standards

One caveat:

Documentation that will be viewed by end users should be created in a way that is best consumed and is most attractive to them Internal development documentation generally does not meet this need

3. Interchange Standards

Deals with the creation of documents in a format that allows others to effectively use

PDF may be good for end users who dont need to edit Word may be good for text editing Specialized CASE tools need to be considered

This is usually not a problem within a single organization, but when sharing data between organizations it can occur

This same problem is faced all the time during software integration

Other Standards

IEEE

Has a published standard for user documentation Provides a structure and superset of content areas Many organizations probably wont create documents that completely match the standard Ten best practices when writing are provided Author proposes that group edits of important documents should occur in a similar fashion to software walkthroughs

Writing Style

Online Documentation
Either internal to the application or Web based Requires rethinking the presentation style since normal paper documentation approaches do not carry over well Should act as a supplement to paper documentation Biggest benefit of Web docs are that they are always current

Document Preparation

Covers the entire process of creating and formatting a document for publication

Author recommends using specialized (and separate) tools for creating and preparing documents

This is only important for user documentation

It is often important to have a professional writer or document publisher evaluate documents before publication to ensure they look good and will carry over to paper well

Document Storage

Author Recommends (in 2001)

File System to store the actual documents Database to store references to the files with metadata to allow searching and referencing

Today it is probably better to use a content management systems

CVS or Subversion
Free

and Open Source Easy to setup and maintain

Conclusion

Good overview of documentation

Though most documentation requirements are based on contract requirements

Hard

this

to cover things like that in a paper like

Most of the content seemed to be referring to user documentation

Design and other similar docs (often times more graphical than textual) were overlooked

Questions?

drekce@gmail.com or I will be here next class