sommerville p143

8/2/2019 Sommerville p143

1/24


2/24

Discussion Topics

1. Introduction2. Documentation Requirements

3. Process and Product Documentation

4. Document Quality

5. Standards

6. Document Preparation

7. Document Storage

8. Conclusion


3/24

Introduction

This paper provides an overview ofthe

Reasons for software documentation

Types of software documentation

Ways to implement softwaredocumentation

Processes and Good Ideas


4/24

Documentation Requirements

General requirements of all softwaredocumentation Should provide for communication

among team members

Should act as an information repositoryto be used by maintenance engineers

Should provide enough information tomanagement to allow them to performall program management relatedactivities

Should describe to users how to operateand administer the system


5/24

Documentation Requirements

In all software projects some amount ofdocumentation should be created prior toany code being written

Design docs, etc.

Documentation should continue after thecode has been completed

Users manuals, etc.

The two main types of documentationcreated are Processand Productdocuments


6/24

Process Documentation

Used to record and track thedevelopment process

Planning documentation

Cost, Schedule, Funding tracking Schedules

Standards

Etc. This documentation is created to

allow for successful management of a

software product


7/24

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 beextracted and moved into the productdocumentation category when theybecome implemented


8/24

Product Documentation

Describes the delivered product

Must evolve with the development of

the software product

Two main categories:

System Documentation

User Documentation


9/24


System Documentation Describes how the system works, but not how

to operate it

Examples:

Requirements SpecArchitectural Design

Detailed Design

Commented Source Code

Including output such as JavaDoc Test Plans

Including test cases

V&V plan and results

List of Known Bugs


10/24


User Documentation has two maintypes

End User

System Administrator

In some cases these are the same

people The target audience must be well

understood!


11/24


There are five important areas that shouldbe documented for a formal release of asoftware application

These do not necessarily each have to have

their own document, but the topics should becovered thoroughly

1. Functional Description of the Software

2. Installation Instructions

3. Introductory Manual

4. Reference Manual

5. System Administrators Guide


12/24

Document Quality

Providing thorough and professionaldocumentation is important for anysize product development team

The problem is that many softwareprofessionals lack the writing skills to

create professional level documents


13/24

Document Structure

All documents for a given product should have asimilar structure A good reason for product standards

The IEEE Standard for User Documentation listssuch a structure

It is a superset of what most documents need

The authors best practices are:

1. Put a cover page on all documents

2. Divide documents into chapters with sections

and subsections3. Add an index if there is lots of reference

information

4. Add a glossary to define ambiguous terms


14/24

Standards

Standards play an important role inthe development, maintenance andusefulness of documentation

Standards can act as a basis forquality documentation

But are not good enough on their own

Usually define high level content andorganization

There are three types ofdocumentation standards ->


15/24

1.Process Standards

Define the approach that is to beused when creating thedocumentation

Dont actually define any of thecontent of the documents

Draft

Revise Check

Peer Reviews


16/24

2. Product Standards

Goal is to have all documentscreated for a specific product attaina consistent structure andappearance Can be based on organizational or

contractually required standards

Four main types:

1. Documentation Identification Standards2. Document Structure Standards

3. Document Presentation Standards

4. Document Update Standards


17/24

2. Product Standards

One caveat:

Documentation that will be viewed by

end users should be created in a waythat is best consumed and is mostattractive to them

Internal development documentationgenerally does not meet this need


18/24

3. Interchange Standards

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

PDF may be good for end users who dont needto edit

Word may be good for text editing Specialized CASE tools need to be considered

This is usually not a problem within asingle organization, but when sharing databetween organizations it can occur

This same problem is faced all the time duringsoftware integration


19/24

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

Writing Style

Ten best practices when writing are provided

Author proposes that group edits of importantdocuments should occur in a similar fashion tosoftware walkthroughs


20/24

Online Documentation

Either internal to the application orWeb based

Requires rethinking the presentation

style since normal paperdocumentation approaches do notcarry over well

Should act as a supplement to paperdocumentation

Biggest benefit of Web docs are that

they are always current


21/24

Document Preparation

Covers the entire process of creating andformatting a document for publication

Author recommends using specialized (andseparate) tools for creating and preparing

documents This is only important for user documentation

It is often important to have a professionalwriter or document publisher evaluate

documents before publication to ensurethey look good and will carry over to paperwell


22/24

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 andreferencing

Today it is probably better to use acontent management systems CVS or Subversion

Free and Open Source

Easy to setup and maintain


23/24

Conclusion

Good overview of documentation Though most documentationrequirements are based on contractrequirements

Hard to cover things like that in a paper likethis

Most of the content seemed to be

referring to user documentation Design and other similar docs (often

times more graphical than textual) wereoverlooked


24/24

Questions?

[email protected]

or

I will be here next class
mailto:[email protected]:[email protected]

sommerville p143

Documents