Software Documentation

1
Software Documentation

• by
• Ian Sommerville

Presented by Kevin Reilly
2
Requirements of Software Documents

• Provide coherent communication between the
  members of the development team(s).
• Facilitate the needs of software maintenance.
• Gives management the information needed to plan
  and budget the development process.
• User documents
• Provide the end user with information on how to
  use the system.
• Provide administrators with information on how to
  administer the system.

3
2 Classes of Documentation

• Process Documentation
• Records the process of development and
  maintenance.
• Product Documentation
• Describes the product being developed.

4
Process Documentation

• Plans, estimates, and schedules used by
  management to predict and drive the software
  process.
• Reports show how resources are used and the
  progression of the development process.
• Standards layout how the process should be
  implemented.
• Working papers ideas and thoughts of the
  development team.
• These often describe implementation strategies.
• These often record the rational for design
  decisions.
• Memos emails day-to-day communication

5
Process Documentation (contd)

• Process docs change as the project progresses
• Process docs are somewhat temporary documents
• Although there is much that can be kept for
  historical purposes.
• Historical info can be of value for planning
  future projects
• Estimating
• Record of how the process evolved for this
  project
• Record of how the ideas evolved

6
Product Documentation

• Consists of
• User Documentation describes how to use the
  product
• System Documentation facilitates software
  maintenance and provides an understanding of how
  the system works.
• Permanent documentation that must evolve with the
  product as maintenance is performed and
  enhancements are made.

7
User Documentation

• Should be structured to meet the needs of all
  users with varying levels of expertise.
• Target audience
• System Evaluators or management
• Novice Users
• Experienced Users
• System Administrators

8
(No Transcript)
9
System Documentation

• Requirements associated rationale
• Description of system architecture
• Description of architecture of each program in
  the system
• Description of the functionality and interfaces
  of each system component

10
System Documentation (contd)

• Source code listings
• Explain complex sections of code
• Provide rationale for coding methods used
• Validation documents describes how each program
  is validated against the requirements
• System maintenance guide
• Describes known problems with the system
• Describes hardware software dependencies
• Describes how evolution of the system was
  accounted for

11
How To Write Bad Documentation

• Spend lots of time on the appearance and
  presentation of your documentation. Your
  management is easily distracted by shiny things,
  and will not realize that your binders contain
  information that could easily be recreated by
  anyone. 3
• Document the Whats and not the Whys. What
  can be uncovered fairly easily, but Why is much
  more complicated.

12
Maintain Quality Documentation

• Document quality is important to the life of the
  system
• It should be clear how to use a system
• It should be easy to understand the system
• The documentation should be up to date
• When system is maintained it is common to forget
  about updating the product documentation.
• It is unlikely that the system will be always
  maintained by the same developers that created
  it.
• 70 of development costs is spent on maintenance.
  So it is wise to make maintenance as easy as
  possible.

13
Minimal Structuring Guidelines

• Cover page with identification data title,
  project name, development team, date of project,
  intended readers of the document,
  confidentiality, etc.
• Documents of more than a few pages should be
  broken up into chapters with sections and
  subsections. A table of contents should be added
  as well.
• Documents with detailed reference information
  should contain an index.
• Glossary may be needed if intended for readers of
  varying backgrounds.

14
2 From the IEEE Standard 1063-2001 Software
User Documentation
15
Types of Document Standards
For consistency and quality assurance,
organizations
can establish the following standards

• Process standards define the process for
  producing high quality documents.
• Product standards define what the documents
  should include, what they should look like, and
  how they should be maintained.
• Interchange standards specifies what editing
  system should be used to maintain documents, and
  provides standard formatting rules.

16
Implement Good Technical Writing Techniques

• Proper grammar usage
• Correct spelling
• Avoid verbosity - try using bullet points or a
  numbering schema instead
• Be precise and define terms that may introduce
  ambiguity

17
Implement Good Technical Writing Techniques
(contd)

• Repeat complex ideas, explaining them in two or
  more different ways - from different viewpoints
  if possible.
• Do not refer to information by reference number
  alone. Include the description for the
  reference.
• Do NOT say Refer to section 1.2.
• Instead, say Refer to section 1.2, which
  describes the interface functional design.

18
Online Documentation

• Do not turn a word-processing document into HTML
  and call it the online document
• Make navigation as easy as possible
• Every page should have a link to the beginning of
  the document
• Make it easy to get the table of contents
• Provide a printable version of the document
• The HTML pages should not be printed.
• There should be a formatted printable version.

19
References

• 1 Ian Sommerville, Software Documentation
  Software Engineering Volume 2 The Supporting
  Processes Second Edition, John Wiley Sons,
  Inc., Hoboken, NJ, 2003, pp. 171-185.
• 2 Software Engineering Standards Committee of
  the IEEE Computer Society, IEEE Standard
  1063-2001 Software User Documentation Software
  Engineering Volume 2 The Supporting Processes
  Second Edition, John Wiley Sons, Inc., Hoboken,
  NJ, 2003, pp. 187-196.
• 3 clover_kicker, HOWTO write bad
  documentation that looks good,
  lthttp//www.kuro5hin.org/story/2003/9/29/104212/11
  2gt
• 4 Deepa L. Melonfire, Writing A User Manual,
  lthttp//www.devshed.com/c/a/Practices/Writing-A-Us
  er-Manual-part-1/1/gt, December 2002.

20
Questions

• ?