The Other Face Or Why Document? By Chris Bradney Or Why Document? By Chris Bradney

First 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 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 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 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 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 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 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 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 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 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-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 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?