Program DocumentationSkill Area 307Materials Prepared by Dhimas Ruswanto, BMm

Lecture Overview• Program Documentation• Characteristics of Good Documentation• Types of Documentation• Stages of Document Preparation

Program Documentation• The program documentation is a kind

of documentation that gives a comprehensive procedural description of a program.

• It shows as to how software is written.• The program documentation describes

what exactly a program does by mentioning about the requirements of the input data and the effect of performing a programming task.

Program Documentation• Documentation are needed to ensure

that we are able to communicate effectively, with all the people who will be involved in the development of the program or system.

• A good documentation will help the user to save their time from spending lots of unnecessary time trying to figure out how to use your program.

Characteristics of Good Documentation• A good documentation is:

–Accessible–Readable–Understandable–Correct–Controlled

Accessible• Documentation is useless unless it is

possible to use it to answer questions.• Users need to find the required document

and the appropriate section to solve a specific problem.

• The document needs to have the following in order to be accessed and found quickly:– A clear structure (proper use of folders

and names)– A table of content– Detailed index– To be catalogued

Readable• Should be written to suit the

knowledge and level of understanding of the user

• Also written in a more personal style and should not assume they are technical expertise

Understandable• Documentation is intended to convey

information to the reader. • This can only be done if the reader is

able to understand the text.• The writer should have a very clear

idea about what can be expected by the reader

Correct• You need to decide two things:

– Is this the right things to document?– Is this documentation correct?

• Correctness requires testing by means of peer view (colleagues).

• No documentation should ever be released without such a review because event the best document writer make mistake and it is difficult to find one’s own mistakes.

Controlled• All programs are subject to change and

this includes documentation.• Extreme confusion can be caused by

mixing up different and incompatible versions of program code, documentation and any other deliverables from the development process.

Types of DocumentationType UseProject Initiation Document

Defines scope of project

End of Stage Report

Defines the status of development at the end of a project stage

Data Flow Diagram

Defines processes and flows of data

Entity Life History How an entity changes over timeLogical Data Model

Relationships between entities

Flow Chart Shows logic of systemStructure Diagram Shows the processing done by a

programDecision Table Defines complex logic

Types of DocumentationType UseProgram Listing Documents a programTest Report Summarizes testing resultsTest Plan Describe how and what will be testedTest Case Describes a particular testTest Data Defines the data to be used with a test

caseModification History

Tracks changes to a system

User Manual Describe how to use a system from user’s perspective

System Manual Describes the operating of a system from a technical viewpoint

Release Notes Describes what has changed since the last release and any special installation requirements

Document Production• Document production is the process of

creating a document and formatting it for publication.

• The document production process as being split into 3 stages:– Document creation– Document polishing– Document production

Document Creation• The initial input of the information

in the document.• This is supported by word processors

and text formatters, table and equation processors, drawing and art packages.

Document Polishing• This process involves improving the

writing and presentation of the document to make it more understandable and readable.

• This involves finding and removing spelling, punctuation and grammatical errors, detecting clumsy phrases and removing redundancy in the text.

• The process may be supported by tools such as on-line dictionaries, spelling checkers, grammar and style checkers and style checkers.

Document Production• This is the process of preparing the

document for professional printing.• It is supported by desktop-publishing

packages, artwork packages and type styling programs.

3 Stages of Document Preparation

END