Great Documentation

1
Great Documentation
Product and Process Development ME En 475/476
2
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

3
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

4
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?

5
Team answers
6
Documentation Objectives

• As a team, identify the three most important
  objectives of documentation for your project.

7
Team answers
8
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

9
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

10
Archive and Access Truth
11
Collaboration
Vendors
Customers
Partners
Shippers
Government
Other Departments
Test Labs
Retailers

12
Collaboration
How can you manage this?
13
Types of Documentation

• Written
• Reports (long and short)
• Papers
• Graphical
• Technical Drawings
• Photo illustrations

14
Technical Drawings as Documentation

• The drawing serves as a common language for the
  product development team, which is typically
  multidisciplinary and multinational/multicultural

14
15
Documentation Audience

• As a team, determine the significant audiences
  for your project documentation
• The audiences need to be people, not
  organizations
• saying the sponsor doesnt count -- its not
  specific enough
• saying the liaison is fine -- we need roles,
  not names
• For each audience, identify a major need for the
  documentation

16
Team answers
17
Instructors need your documentation to

• communicate your results so others can make
  important decisions about how to use your work,
  and gage the success of the project.
• 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.)
• establish the credibility and quality of your
  work and your design.

18
Instructors need your documentation to

1. provide sufficient detail so that someone could
   repeat your work and get the same results.
2. enable deeper thinking about your project so that
   all involved can make better design decisions.

19
COACHES need your documentation to
20
Project Liaisons need documentation to

• Show that theyve 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

21
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

22
Tips for Great Documentation

• BE THE READER!!!!
• Is this material true?
• Is it understandable (logical in presentation)?
• Is it eloquent (fluent and persuasive)?
• Use Pictures
• Use Whitespace
• Use Appendices
• Use Navigation Guides

23
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 cant be
  misunderstood

24
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

25
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

26
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 doesnt
  need to contact you during the re-creation
  process

27
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

28
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

29
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

30
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

31
Other ideas???
32
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)

33
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.

34
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.

35
What might you include

• Cover Page
• Executive Summary
• Table of Contents
• Project Objective Statement
• Project Introduction
• Project Results
• Conclusions and Future Work
• Appendices