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