Winter Documentation: Common Mistakes

Use the Fall Document and the Winter Document Assignment as guides. Here are a few common issues that we've noticed for various sections:

• The Executive Summary is omitted for Winter and replaced with your Brochure.

• Design Requirements: This is the most challenging section, as it concisely summarizes all of your key learnings and rationale for your detail.

  • Properly introduce the section, including the purpose of it, and where the requirements came from.

  • Make your metrics for the requirements measurable. If you're struggling to come up with a metric, it may mean that your requirement is not well defined enough and may need to be more specific. For example, there absolutely should not be Product must be comfortable as a requirement. Your team should have explored this, and have discrete physical requirements for what comfortable is.

  • Make sure people are not defining a possible opportunity as a requirement. For example, Solution must have wheels to move around is an example of making the opportunity of giving the solution wheels a requirement. Instead the requirement should be The solution must be able to move around.

• Design Development: Your development is supposed to start at the fall quarter and go until the final solution. This means that sections from fall and winter are necessary to show the entire development. Key rules:

  • Tell your whole design story on how your idea developed (including parts from Fall, winter and spring). The best way to do this may not always be chronologically.

  • Any additional work that did not ultimately have a big impact on the final design should be referenced in the Appendix.

  • Don't rely on 310 jargon. If you reference your Dark Horse prototype, explain what that means.

  • When describing a prototype, be sure to talk about the 3 main points: what questions the prototype was supposed to answer, what you built and how you tested it, and ultimately what you learned.

• Design Description: The purpose of this section is to allow for others to recreate ONLY the final solution from just looking at this section. There should be NO description of why you built it this way. That should have been covered in the design development section. This section is ultimately mostly pictures and some explanatory text. Here are some things that should be placed here:

  • A Bill of Materials (BOM), or at minimum a parts list

  • Exploded view assembly drawings, and diagrams showing how everything fits together

  • General dimensions, and a reference to where all the detailed mechanical drawings are in the Appendix

  • Block diagram showing connectivity and/or wiring diagrams

  • Circuit diagrams

  • State diagrams of how any code works, and a reference to the actual commented code in the appendix (Please don't put any real code in this section...)

• Planning: This is not just a list of all the assignments that were due. This is your time to reflect on your process, and paint a picture of how you really managed the project. Talk about real milestones for your team (key turning points, your own prototypes) and what worked and didn't. The successful planning section also addresses how you managed global communication. Summarize your budget and show where the bulk of your funds were spent. It's appropriate to put the detailed budget in the appendix and reference to it.

  • In any case, the most valuable part of the Planning section is what you plan for spring. It is a critical element of how your liaisons (and the TTeam) will evaluate the status of your project. We will revisit this plan in early spring SGMs.