Documentation

1
Documentation

• Assignment 10
• Christine MacGregor
• Alex Goulet
• Ray Rawana

2
System Documentation

• Intended to help programmers and analysts to
  build and maintain the system.
• UML language tools such as Jude can help in the
  creation of use-cases, flow charts and behavioral
  diagrams.

3
System Documentation Contd

• Anything from the beginning to the end picked up
  and used to describe the system can be used for
  system documentation.
• Automated documenting tools also do exist. Such
  programs are Cherryleaf which automates IT
  documentation, and Texinfo which minimizes the
  amount of documents needed initially and can
  create other documents and diagrams from one file.

4
System DocumentationNice-to-haves

• Initial brainstorming sessions, JAD sessions,
  etc.
• Not needed to put into the system documents, but
  still nice to see where the information came
  from.

5
User Documentation

• Consists of manuals, training manuals, online
  helps systems, etc)
• Materials for the end users or those who have to
  use the system after it is implemented and
  online.
• These users do not require the system
  documentation because they will be only using the
  system for its intended purpose and not
  rehashing, reworking, or debugging it.

6
User Documentation

• Usually left at the end to be made which is not a
  efficient practice.
• Requires to be written, edited and tested
  frequently and thoroughly.
• Takes approx. 2-3 hrs per page single line for
  paper based or 2 hrs per screen for online.
• A simple set of documentation of a 10 page manual
  will take 70 hrs to complete.
• Lower quality can also be met for speed, but will
  result in a sub-par manual.

7
User Documentation Contd

• Creating the documentation starts at the
  interface design and when the specifications are
  done.
• Drafts are done as soon as the unit tests are
  completed.
• They will go through several revisions at this
  point.

8
User Manual/ Tutorial Styles

• Manuals are designed to be read individual
  whereas Tutorials are to be read in sequence.
• Tutorial entries are usually longer since they
  are teaching the user step by step.
• Using a search function for online help will
  allow the tutorial or manual to be found easier.
  The same information can be shown in different
  formats. The material can be interacted in more
  ways and it is inexpensive to write and post
  these documents.