Guidelines for Project Documentation

Guidelines for Project Documentation

This handout gives the suggested contents of report, and the suggested style for your term project. (Note that the purpose of this guideline is not to discourage you, but to show what the database documentation should look like.)

1.Basic Principle of Documentation

The basic principle of documentation in any report is very simple: readers should be able to understand your work and grade your project by just reading your report without you. For this purpose I suggest you keep in mind the following four points.

1)Readers of your report should be able to tell what you have accomplished. For example, you can include the following ideas if they are relevant to your problems: what problems you have worked on, what assumptions you have made in your work, how much you have accomplished, what parts you did not finish (or limitation of the result of your work: do not try to hide the problems; nobody's work is perfect), how well you did, how important your work is, why it is important, where it can be applied, what kinds of difficult problems you had during your work, what the remaining problems are, what parts can be done as next steps, etc.

2)The report should be easily readable and understandable. No matter how significant your work may be, it is not worth full credit, if you cannot convince readers. Use clear and concise English. Keep in mind you should write to communicate with readers, not document for yourself.

3)The report should be well organized. It should have a clear logical sequence. Organize your work in chapters, sections, and sub-sections with meaningful headings. Include diagrams, tables, or figures whenever appropriate.

4)The report should be self-contained, if possible. Do not ask readers to look around other references, unless you have a reason to do so.

2.Contents of Report

2.1.Application Development

1)A summary of the problem and an overview of your work.

2)Detailed problem Description

a)Problem Descriptions

b)Assumptions

c)The way you obtained your information

d)Your methodology to solve the problem

e)Environments (e.g., hardware, software, equipment, policy of the company, etc.)

f)Any special considerations specific to your problem

3)Conceptual design

a)Required operations or frequently expected queries, reports, etc.

b)ER diagram and its explanation (Explain entities, relationships, cardinalities, and attributes)

c)Relational schema

d)Data Dictionaries

e)FDs and Normalization

f)Routine queries and report types

4)Implementation

a)Organization of the overall program

b)Brief explanation of each module

c)Specify previous work and your work

d)Indexing schemes

e)How to run the program

f)Problems you encountered during your work

g)Limitation of the work

h)Future work

5)Conclusion

a)Summary of your work including limitations

b)Lessons learned

6)References

7)Appendix

a)Sampleinput

b)Program listing

c)Sample output

d)Graphical User Interface (GUI) Layout and its screen shots

e)User Documentation

i)Installation instructions

ii)README:explaining how to interact with your system

f)All source programs that are developed for your system

g)Division of work (i.e., each member’s contribution)

2.2.Documentation of Code

The implemented program must document the following instructions.

1)Each query must fully explain what the purpose of the query.

2)All source programs must have names of your group members, term and year.

3.Best Documentation Principle:

DO NOT WAIT UNTIL YOU COMPLETE YOUR PROJECT. CREATE INCREMENTAL DOCUMENTATION: WRITE AND MAKE NOTES WHENEVER YOU HAVE FRESH IDEAS.

1)How to Lose Some Points in the Documentation with Excellent Work

I suggest you read and follow the guidelines above. Here are some wonderful ways to lose some points on documentation with your excellent work.

a)When there is no summary section in the first page of the report. The summary should show a brief overview of the whole project including goals, methods, conclusions and systems used.

b)When I couldn't understand what you have done by reading the first two pages of your main discussion.

c)When there is no CONTENTS section with page numbers. I have to flip over pages to find information that I need.

d)When your documentation does not follow the logical order of the problem solving process. It should follow the order of Introduction, Conceptual Design, Physical Design, Conclusion, and Appendix.

e)When it does not have a section on "How to install" and "How to run" section.

f)When your direction in the sections does not match with actual screen dialog.

i)After copying all of your programs into one directory, try to install and run by yourself as in your documentation to see whether there is any problem.

ii)Check whether the procedures and dialogs are the same as your documentation.

iii)Check for directory and access path problems.

g)When you wrote your documentation by assuming that I am familiar with your database system and application problem. You have to write in a manner explaining your work to someone who is not familiar with your system and application. It should be self-contained as much as possible.

1