Program Documention

1
Program Documention

• Carl Smith
• National CertificateYear 2 Unit 4

2
Unit 4 objectives

• Apply simple analysis and design techniques to
  the software development process.
• Develop basic high-level code using an
  appropriate procedural programming language.
• Use suitable testing methods to ascertain the
  correctness of a working piece of code.
• Produce appropriate documentation for a given
  program application.

3
Step 4 - Document

• Documentation is not just for others to
  understand your coding
• In 6 months time you may not follow your own
  logic!
• SO
• Documentation is important

4
The first impression

• Include a facing page with the Document title,
  also include-
• A brief introduction
• Table of contents
• Author YOU..!
• Date
• Headers/Footers
• Page numbers

5
Program Specification

• A description of the program in plain
  English.This would be the program specification.
  In the case of your assignment it means repeating
  the question.

6
Assumptions

• A list of any assumptions or decisions you
  make.In theory the program should be so well
  specified that you dont have to assume or decide
  anything.
• In practice this never happens. Justify the
  assumptions and decisions you make whenever
  possible.

7
Your algorithm

• Your program designDetail the algorithm you are
  employing to solve the program problem.
• Dont worry that it seems obvious to you
  there are always more ways of solving a
  particular problem than any one person can see.
• If you considered alternative algorithms explain
  why you prefer the one you chose.

8
Design tools

• The design tools normally used are flow charts
  and pseudo-code. A flow chart is always a good
  idea because any reasonably intelligent person
  can understand one even if they know nothing
  about programming.
• Pseudo-code forms an excellent initial comment
  structure for your code.

9
Source code

• Your source codeThis should be well commented
  Self Documenting Code.Use a fixed width
  font e.g. Courier - to differentiate it from
  the document text

10
Program Deficiencies

• Detail any deficiencies in your programIf your
  program cannot handle certain inputs, or handles
  some situations inelegantly, state these.
• Its better to produce a program that deals with
  95 of cases, than struggle to solve every case
  and end up not producing a working program.

11
The Test Plan

• Record your test plan, and list the
  resultsRemember that a successful test is one
  that finds an error.
• Try to break your program dont try to
  convince yourself it works.

12
The User Guide

• A critical document, often neglected and
  sometimes poorly done, is the user guide which
  informs the user community how to work the new
  system.
• Nothing can save a poor system, but a decent
  system can be made to look poor if the user
  documentation is inadequate or unfriendly.
  (Programmers are generally considered to be the
  worst producers of user guides)

13
Finally!

• Anything else interested parties might benefit
  from knowingIf theres something else someone
  needs to know in order to understand how your
  program works, or in order to use your program
  include it in your documentation.
• Thats why you produce program documentation to
  expose your thinking processes to the world!

14
Summary

• We covered-
• National Certificate Unit 4 objectives
• The importance of documentation
• The documentation plan
• Any Questions?