Collab Research Proj I and II
Suggested Documentation Guideline
Both "under documentation" and "over documentation" are not desirable for any software projects.
This guideline tries to include essential items.
Title Cover Page Format
Table of Contents
Project Abstract
Introduce an acronym of your system. Use the acronym consistenly later on in the documentation.
Three to seven paragraphs long to summarize goals of your project,
how you develop your system, what you developed, and the summary test results of your system.
This section should be concise, however, do not itemize.
Keywords
List keywords related to your project.
Project History and Background
If you continue/improve previous project done by youself or others,
describe about the old system and the reason why and how you modify the existing system.
If not, describe similar systems already developed by others (on the market).
If you are developing such a system for the first time in history, declare it here!
Requirement Specification
This section is to specify the requirements from the user perspective. Do 'not' include
anything about design and implementation from the perspectives of developers.
Must include the following items:
- System Context Diagram with external entities(users) and input/output descriptions
- System Function List with short description for each function. Please itemize.
- System level Sequence Chart for each major system function (feature), if necessary.
This shows dynamic user scenario with time concept. Normal case will be sufficient.
- State Transition Diagram (System level or User level), if needed
- Data modeling using ER diagrams. This is required, if any database is involved in the project.
The diagram must show entities, attributes, relationships, cardinality, and modality. The use
of modelling tools such as DBdesigner 4 is
highly recommended.
System Design Document
This section is to specify how you design the system. Must include the following items:
- Systems not requiring OO design: System (hierarchical) Diagram (or Abstract system model) and Block (Interaction) Diagram. A block is a physical implementation unit such as a file.
Must show information/control flow between the units for each level.
- Systems requiring OO design: The use of UML tools is required.
Rational Rose
is the most popular tool but you may use any.
Here
are list of UML tools.
- (New) Technologies used, if any
- Design choices considered, if necessary
- Design notes
- SQL files to initialize database(s) and to populate initial data, if needed.
Make sure the data model is normalized.
Implementation Notes
- (New) Technologies used, if any
- Implementation choices considered, if any
- Implementation notes, if any
- Deployment procedures, directory sturcuture, account (login) information.
- Algorithms, if necessary
Manual
Must include the following: Readme file to describe how to install, start (launch), test, and/or
use the system; and
'brief' manuals for the users. Also, you 'must' list all the passwords
such as login, database, and admin account passwords for the advisor
to test/maintain the system, if necessary.
Test Results and Conclusion
Show all the tests (alpa and beta tests) you did and summarize the results.
Future Improvements
List any function you did not complete. Explain why you could not.
List all the known bugs.
Suggest any ideas to improve the system for the future.
Acknowlegements
Course name, advisor name, etc.
Workload Distribution
This section is only for group projects.
Identify the work done by each team member. It is recommended to use a table and show
the percentage of the work done by each member.
References
List all the information you were using such as books, manuals, website URLs.
Appendix: Hard Copies of Source Codes
Try to make your code as self-documenting as possible.
You must follow programming standards such as
block and line comments, indentation, meaningful names, etc.
Appendix: A floppy or CD-Rom
It is recommended to zip all the files into one zipped file.
- Capstone documentation file itself
- Readme file for installation and start to use
- Source code files
- Executable files, if needed.
- Manual files
- Test data files
- etc.