Upload
ashish-bhole
View
230
Download
0
Embed Size (px)
Citation preview
8/2/2019 Sommerville p143
1/24
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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/2/2019 Sommerville p143
8/24
Product Documentation
Describes the delivered product
Must evolve with the development of
the software product
Two main categories:
System Documentation
User Documentation
8/2/2019 Sommerville p143
9/24
Product Documentation
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
8/2/2019 Sommerville p143
10/24
Product Documentation
User Documentation has two maintypes
End User
System Administrator
In some cases these are the same
people The target audience must be well
understood!
8/2/2019 Sommerville p143
11/24
Product Documentation
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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 ->
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
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
8/2/2019 Sommerville p143
24/24
Questions?
or
I will be here next class
mailto:[email protected]:[email protected]