Great Documentation
Product and Process
Development
ME En 475/476
Upcoming Schedule
• October Coach reviews – due Wednesday
• October Peer reviews – coming up this
week
• Design review 2: two weeks from tomorrow
• Design exam – in testing center starting 2
weeks from Wednesday
2
Objective & Outline
• How important is project documentation?
• What are the objectives of documentation?
• Who is the audience for Capstone
documentation?
• How can we do a great job with
documentation?
• The main documentation assignment
3
How important is
Documentation?
• Get together with your team, and discuss
the following questions:
• How important is documentation, really?
• How much of your time should be spent doing
documentation?
• Does doing documentation help or hinder your
progress on the project?
Team answers
Documentation Objectives
• As a team, identify the three most important
objectives of documentation for your
project.
Team answers
What I really believe…
Documentation:
• the process of providing written details or information
about something
• documents provided or collected together as evidence or
as reference material
Through great documentation:
• I can shine (get self/team/product noticed)
• I can archive and access truth
• I can collaborate
Getting noticed
Learn to communicate well and write clear,
succinct, accurate, and even eloquent
reports.
Two major parts to getting noticed:
• Great technical work
• Great showcasing of that work
Archive and Access Truth
Collaboration
How can you manage this?
12
Types of Documentation
• Written
• Reports (long and short)
• Papers
• Graphical
• Technical Drawings
• Photo illustrations
Technical Drawings as Documentation
The drawing serves as a common
language for the product development
team, which is typically
multidisciplinary and
multinational/multicultural
14
Documentation Audience
• As a team, determine the significant audiences for
your project documentation
• The audiences need to be people, not organizations
• saying “the sponsor” doesn’t count -- it’s not specific
enough
• saying “the liaison” is fine -- we need roles, not names
• For each audience, identify a major need for the
documentation
Team answers
Instructors need your documentation to
1. communicate your results so others can
make important decisions about how to
use your work, and gage the success of
the project.
2. inform others what design decisions your
team made and why you made them.
(Provide enough detail so that your audience can see
your logic and agree that your logic is logical.)
3. establish the credibility and quality of your
work and your design.
Instructors need your documentation to
4. provide sufficient detail so that someone
could repeat your work and get the same
results.
5. enable deeper thinking about your project
so that all involved can make better design
decisions.
COACHES need your documentation to…
Project Liaisons need documentation to
• Show that they’ve done a good job of coordinating the
project
• Show that the project meets company needs
• Be suitable for passing up the line
• Stand alone as an excellent summary of the project
Champions need documentation to
• Demonstrate that the team is doing a great job of meeting
the company need
• Demonstrate that the educational objectives of Capstone
are being met
• Demonstrate that spending the money on Capstone
projects is worthwhile to the company
Tips for Great Documentation
• BE THE READER!!!!
• Is this material true?
• Is it understandable (logical in presentation)?
• Is it eloquent (fluent and persuasive)?
•
•
•
•
22
Use Pictures
Use Whitespace
Use Appendices
Use Navigation Guides
Plan  Create  Refine
Plan
• Put someone in charge of making sure the team
creates great documentation
• Figure out what the objective is
• Figure out who your audience is
• Understand the required mechanics
Create
•
•
•
•
Create an outline (or a few, and pick the best)
Choose a logical, easy to read order of things
Figure out how appendices support your outline
Write succinct sections that can’t be
misunderstood
Plan  Create  Refine
Refine
• Have each member read and comment on the
document in detail
• Consider the “other” perspective
• Use many useful photos and illustrations
• Polish the grammar, the look, the layout
• Let others (outsiders) provide honest feedback,
and be open to their comments
• …
Conciseness
'I have made this [letter] longer, because I
have not had the time to make it shorter.’
Blaise Pascal - "Lettres provinciales", letter
16, 1657
What Past Students Think…
“Good documentation is being able to pass
along your design and having the next
person being able to re-create exactly what
you intended. Great documentation is
when the next person doesn’t need to
contact you during the re-creation
process”
What Past Students Think…
“Documenting should allow someone after
you to duplicate or close to duplicate your
work. I have never heard anyone
complain about their predecessor
having documented too much”
What Past Students Think…
“Say what needs to be said as clearly and
concisely as possible”
“A document needs to be clear and concise
for the intended audience”
What Past Students Think…
“Documentation should not be superfluous.
Good documentation should contain a brief
description of the motive, or problem, with
the results and show how these results
were derived; everything else belongs in an
appendix”
What Past Students Think…
“Great documentation is comprised of two
main elements: [details and summary].
The summary is the pretty exterior, the
detail is the blood and guts. 95% of your
audience will thank you for the summary,
the other 5% will worship you for your
thoroughness”
Other ideas???
Fall Semester Report
• Two phases of report submission
• First submission and Final submission
• 10 page limit, appendices are additional
• Report should be understandable without
reading the appendix. Appendix should be very
easily navigable.
• Guidelines for structure are on pages 46 and
47 in guide – but teams can adapt (see page
45)
Fall Semester Report
• Each submission is graded by three coaches
• Coaches use their professional judgment to
evaluate each submission according to pages
42-43 in guide
• For first submission: Coaches will provide the
team with meaningful feedback focused on the
TOP 3 things the team could do to improve the
report for the final submission.
Fall Semester Report
• For final submission, judged on each criterion
on pages 42-43 in guide. Coaches provide only
a few notes to help the students know why they
judged it as they did.
• For both the first and final submissions, submit
via email.
• Make ONE pdf file.
• Limit its size to 20 MB.
What might you include…
•
•
•
•
•
•
•
•
Cover Page
Executive Summary
Table of Contents
Project Objective Statement
Project Introduction
Project Results
Conclusions and Future Work
Appendices