Transcript Lecture 6: How to write your project documentation - Part IV

Lecture 6: Writing the Project Documentation
Part IV
Documenting Software
 Issues covered in Software Documentation
 Internal commenting of program code
 System’s analysis and design notes
 Figures and system’s documentation
 Test plans
 User guides
Documenting Software
 List of topics and documentation you might be
expected to cover and include in your project:
 An introduction / Overview
 Technical solution adopted
 Design: System analysis, system design, human factors, etc
 Software engineering information: Structure, definition languages and







test plans
Development approach used
Problem encountered
Limitations / restrictions
Hardware/software requirements
Next stage
Evaluation of the project
User guide
Documenting Software
 Commenting Program Code
 Dependant on the programming language used
 Guidelines to follow when commenting your program code:




Understand the purpose of the program you are writing
Try to ensure you provide the right level of comments within your
program. Don’t over-comment or under-comment. And avoid
commenting on every line in the code
It is advisable to comment each function, procedure, object, block,
screen, etc. This will explain how each component of your program
work.
Try to make your comments separated from your code. Use widely
the separate line comments, instead of in-line comments
Documenting Software
 Commenting Program Code
 Continue: Guidelines to follow when commenting your
program code:




Keep your comments brief and clear.
Don’t waste time in producing fancy comments. Comments
are added to enhance understanding of your program not to
make it prettier.
Make sure that you add vital information at the beginning of
your program, such as: author, date, version number,
description of what the program does, and brief explanation
of how it does it.
Make sure to update your comments if you have modified your
code
Documenting Software
 Writing User Guides
 Any user guides you develop are likely to be presented
within separate document to your final report, or
included within its appendices.
 The longer user guides are, the more sensible it will be
to produce them in separate document.
Documenting Software
 Writing User Guides
 A user guide, should provide the user with the following
information:






An overview of the software
An idea of its hardware requirements (memory, disk space,
additional hardware requirements such as, sound cards,
operating system requirements, etc.
How to install the software
How to start the software
How to end or uninstall the software
Details of any known problems and restrictions imposed by
the program
Documenting Software
 Writing User Guides
 A user manual, should satisfy three aims:



To provide practical information about the software when
help is not at hand
To help inexperienced users get started quickly and with least
difficulty
To help experienced users become productive quickly