Document Templates, Samples and Ramblings to Explain
Them
Last modified: 24 April, 2002
Some basic notes to help you get going in your group...
Time Logs and Meeting Agendas
On all of the milestones, you are asked to submit a time log and a set
of meeting agendas/minutes. These are usually worth 5 points apiece - so
10% of your grade is a no-brainer, but it will be impossible to get an
"A" if you don't turn them in.
So what are they?
The time log is literally that: a list that shows how much time each person
spent on the project. This should be a running total, so we can tell how
long you spent on each milestone and how long you spent on the entire project.
The time logs are used to track the time of each individual, both when
meeting as a group and working alone. An observation: the successful teams
in the past have spent most of their time working together in the beginning,
really getting to understand the requirements, then tapering off and doing
most of coding individually.
The meeting agendas/minutes is a list of the meetings your group held,
the meeting date, the topics you planned to discuss and any decisions or
action items that came out of the meeting. Action items must be tagged
with who's responsible for clearing them.
Why do we make you do time logs?
One of the hardest things for software engineers to do is make accurate
estimates of the amount of time it takes to do a task - we tend to just
think of the time we are actually typing the code. When we consistently
underestimate times, we lose credibility. By having you track your time,
particularly the time you spend in your group, we hope you'll start developing
an appreciation for how long things really take.
Why do we make you do agendas and minutes?
We make you do agendas because when you meet, you can't afford to waste
time - you're not just wasting your own time, your wasting that of your
team members, as well. To avoid wasting time, you need to figure out in
advance what you're going to talk about so (1) everyone can prepare properly
and (2) you invite only the people who have to be there. By the way, telephone
conversations can count as meetings, too - they don't have to be face-to-face
in the same room.
You have to do minutes to help you remember what you agreed to do and
so that you can remember who got assigned responsibility for what. This
is really important when it comes time for the milestones to be delivered.
How are they graded?
Mostly by an "existence" criteria. I look at them to make sure that you
understand that both group and individual times are recorded, that you
*are* having some meetings, that you are documenting decisions and that
you're taking action items. The documentation of decisions and action items
can be little bullet phrases - I don't have to understand them, I just
want to feel like you do.
-
A template for your time logs.
-
A sample of a group time log.
-
A template for your agendas/minutes.
-
A sample of the documentation for one meeting.
This table grows as you have more meetings.
Supplementary Material for the Project Milestones
The supplements start off with a roadmap to
this document set.
Then, links are provided to a set of documents for each milestone deliverable.
The document set for each milestone is different, depending on what we
thought was appropriate. Some of them have templates and annotated templates
and examples and instructions . . . and some of them have just an example
and a roadmap. This is because
-
it's important that some things be structured in a certain way,
-
some things lend themselves to being templated, and
-
students in the past have had lots of trouble in some areas and breezed
through other areas, so we tried to concentrate on the trouble areas.
All the samples are set up around a game coded in java, Dots & Boxes.
This is the help file for it.
All the document samples linked from this document are in HTML format
for easy browsing. Microsoft Word '97 versions are also available here.
The document names are the same as the HTML versions, but with a .doc extension...
(To look at them on a machine running Word, just click on the link. To
save them as Word documents, right click on the link and "Save Target As".)
Project Proposal Form
Requirements Documentation
-
A template for the System Requirements
Document (SRD). This borrows heavily from the work of Brian Lawrence and
Don Gause. If you want to see the work of the Masters, check out http://www.coyotevalley.com/
-
An annotated template for the System Requirements
Document. There's way more information here than you will use, but if it's
the middle of the night and you don't think you'll get a response from
me soon enough to meet your needs, look here.
-
A completed SRD for the ongoing Dots and Boxes
example.
-
A list of rules on how to write well-formed
requirements for this class. You have to write them this way to get
through the System Test, so do it now rather than do poorly on the SRD
Milestone and have to redo it just before the end of the quarter.
-
The grading sheet, with point allocations,
that will be used to grade the SRD.
User Manual
NOTE: These files did not convert from Word very well, and lost many of
the images. I do not have the time to reproduce them, but you can find
the original Word documents here. You are also welcome
to visit me and look over the documents produced for previous projects.
UPDATE 4/24/02 3PM There was an error with the User
Manual Template. The second column of the traceability matrix was wrong
- It should be "User Manual Section". This has been corrected in the
HTML files.
Design Documents, Part 1
What's due?
-
Class Diagrams
-
Sequence Diagrams
What's here?
-
A roadmap for Detailed Design, part 1
-
A description of class and sequence diagrams.
-
A sample set of structure, inheritance and
association class diagrams for Dots & Boxes.
-
A sample set of sequence diagrams for Dots
& Boxes.
-
The grading sheet, with point allocations,
I'll use to grade the Design Documents, part 1.
Design Documents, Part 2
NOTE: If you find the slide presentations are difficult to read, you are
welcome to stop by BE164 and look at the hard copies which are perfectly
legible. You can even photocopy them if you wish for future reference...
For this milestone I highly recommend using the JVision tool from Object
Insight to do the UML portion of this milestone. It is free, and linked
to from the main homepage. One of the more useful aspects of the software
is that you can 'slurp' in your existing objects and it will diagram them
for you...
What's due?
-
Class diagrams
-
Sequence diagrams
-
Data Dictionary - if using Java, then use javadoc to generate what's
needed
What's here?
-
A roadmap for Detailed Design, part 2
-
A description of class and sequence diagrams.
-
A sample set of structure, inheritance and
association class diagrams for Dots & Boxes.
-
A sample set of sequence diagrams for Dots
& Boxes.
-
A sample of a design data dictionary
for Dots & Boxes when not using javadoc.
-
The grading sheet, with point allocations,
I'll use to grade the Design Documents, part 2.
Code and Coding Standard
What's due?
-
Commented code
-
Coding Standard
What's here?
Test Procedure/Report
What's due?
-
Your complete (run) test procedure
-
Your Test Report, summarizing the results of the
test run
What's here?
-
A roadmap for
writing your Test Procedure and doing your Test Report.
-
A template
for a test procedure.
-
A sample
of a test procedure for Dots & Boxes.
-
An example
of a test report.
-
A template
for a test report.