The Other FaceThe Other Face

Or Why Document?

By Chris Bradney

Or Why Document?

By Chris Bradney

First StepsFirst Steps

There are two, not one, important sides to every program product

Unfortunately, the other face is typically poorly done or incomplete

Must everyone knows why, but fail to know how

There are two, not one, important sides to every program product

Unfortunately, the other face is typically poorly done or incomplete

Must everyone knows why, but fail to know how

Main topics in documentationMain topics in documentation

Information on its use Information on how to verify its

correctness Information on how to modify

Information on its use Information on how to verify its

correctness Information on how to modify

How to use a program documentation

How to use a program documentation

We need a broad overview of the program Probably the most lacking piece of

documentation Smaller details can be added elsewhere

Need to use fully sentences and paragraphs for the reader to understand

We need a broad overview of the program Probably the most lacking piece of

documentation Smaller details can be added elsewhere

Need to use fully sentences and paragraphs for the reader to understand

How to use a program specificsHow to use a program specifics

There are nine main elements that the user needs in the documentation Purpose Environment Domain and Range Functions and Algorithms Input-output Formats Operation Instructions Options Run Time Error Checking

There are nine main elements that the user needs in the documentation Purpose Environment Domain and Range Functions and Algorithms Input-output Formats Operation Instructions Options Run Time Error Checking

Verifying a program documentation

Verifying a program documentation

Documentation detailing methods for verifying the validity of the program are often absent

Need test cases to check for the main functions, as well as both sides of the border conditions

Documentation detailing methods for verifying the validity of the program are often absent

Need test cases to check for the main functions, as well as both sides of the border conditions

Modifying a program documentation

Modifying a program documentation

Need to have insight into the internal structures of the program

Used for adaptation of a program or maintenance of the program

Documentation needs to be clear, concise, and accurate

Need to have insight into the internal structures of the program

Used for adaptation of a program or maintenance of the program

Documentation needs to be clear, concise, and accurate

Documentation of the internal structures

Documentation of the internal structures

What is needed: A graph of the internal flow (flow chart) Algorithm descriptions and references Explanation of file arrangement Overview of sequence of events Observations of modifications and hazards

What is needed: A graph of the internal flow (flow chart) Algorithm descriptions and references Explanation of file arrangement Overview of sequence of events Observations of modifications and hazards

Case against the flow chartCase against the flow chart

The flow chart is good for introduction to algorithmic thought processes

Flow charts are not used often by experienced programmers

Flow chart concepts can be illustrated better in other forms

The flow chart is good for introduction to algorithmic thought processes

Flow charts are not used often by experienced programmers

Flow chart concepts can be illustrated better in other forms

Documentation integrationDocumentation integration

It is better to have documentation mixed with the source code rather than as a separate entity

The assurance of accuracy and consistency paramount

Gives the reader a more in depth look at the processes, not abstracted

Assures completeness of documentation

It is better to have documentation mixed with the source code rather than as a separate entity

The assurance of accuracy and consistency paramount

Gives the reader a more in depth look at the processes, not abstracted

Assures completeness of documentation

Integration practicesIntegration practices

We can use the forms that are included in high level programming languages to show concepts

Use comment blocks to place needed prose in code

We can use the forms that are included in high level programming languages to show concepts

Use comment blocks to place needed prose in code

Case against self-documentingCase against self-documenting

Source code is longer with added documentation

Takes more time to write with documentation

Difficult to incorporate charts and graphs

Source code is longer with added documentation

Takes more time to write with documentation

Difficult to incorporate charts and graphs

Concluding thoughtsConcluding thoughts

Documentation is as important as the program itself, but is often neglected

Documentation should be written as to be understandable by someone unfamiliar to the project

Self-documenting code improves vital areas such as accuracy, consistency, and completeness

Documentation is as important as the program itself, but is often neglected

Documentation should be written as to be understandable by someone unfamiliar to the project

Self-documenting code improves vital areas such as accuracy, consistency, and completeness

Questions?Questions?