Winter Documentation Guidelines

Template

Most people will be using their Fall document (e.g. from the Overleaf template) as a starting point. For additional guidance: 

• Please review the page for common mistakes in Winter Documentation.

• Please review in detail the markups and Googledoc comments on your Fall report. The same guidance will apply in Winter. Winter builds on Fall. Make it better as well as longer!

• Additionally, here is a read-only copy of the Xylem 2020 Spring Latex document which is a rather good detailed example with various formatting niceties. 

Expectations

We expect a succinct and clearly visualized (with annotations) representation of your thinking and doing during Winter Quarter. Clearly communicate to outsiders and especially your corporate client team: 1) what your Design Team did; 2) why you did it; and 3) what you learned from doing it.

Engage all team members, local and distant, in the documentation of your team's Winter Quarter Journey. Assume that the reader is charged with picking up your project. What do they need to know to carry it forward? If you can help these strangers, you are probably helping yourself by creating a more useful document.

Document the current status of your design requirements. How do your prototypes satisfy the requirements? Have new requirements been discovered? Reveal your plan for delivering the final prototype in Spring. 

Description

The fall design documents are a good starting point for your winter documentation, but only a starting point. The content philosophy and formatting advice in the detailed documentation templates still apply. The mechanics and formatting are the same.

For winter, we have a slightly modified outline with regard to the fall. You don't need a new template but you will need to adjust some section headings. The major sections, and the rubric for evaluating them, are as follows:

Final Winter Brochure (If you only read this section, would you fund the project?). This again is in lieu of an Executive Summary (which we will ask for in Spring).

1. Context and Front Matter (Why is this project being done? Are key terms defined?)

• Is there a decent glossary of non-obvious terms? Winter glossaries tend to be considerably richer than in Fall.

• Does this section make a good case for the user Need that motivates the project?

• Are the team and project circumstances adequately explained?

2. Design Development (How was the design space explored? )

• Is there enough detail to understand what the current status is and how it was reached and why?

• Were any parts unclear? If so, which?

• Are there parts that could be omitted? (Early benchmarking, brainstorming details are usually moved to Appendices for winter, with just a short summary in the main document. Focus on the newer stuff.) Design development sections do not need to run to many pages.

• Make sure your text that describes developments refers explicitly to figures (hopefully annotated).

Tip: Do not feel compelled to stick to a strict chronology of "we did this... and then we did this..." -- the important thing is to understand what was learned and how it leads to the current design. The best Design Development sections tell a cohesive story of the design. Fall results should be included, but in condensed and concise form.

3. Design Requirements (What should the system do?)

• Is it clear what the design must do? In comparison to fall, you should have a better understanding of requirements.

• Is there enough detail in the functional and physical requirements to be able to assess whether a particular solution will be satisfactory or not?

• Are functional and physical requirements properly distinguished?

• Is the team clear about what is a requirement vs. a constraint (or an opportunity)?

Tips: Review the feedback on your fall requirements. Recognize that you know much more about the design space now. You have discovered many requirements and you are more concrete about them.

4. Design Specifications (Are resulting specifications explicitly related to the requirements?)

Ideally these should map to your requirements. This section does not need to be very long but it should provide enough information for somebody to fully understand the latest & greatest incarnation of your design including:

• physical properties (e.g. CAD drawings, assembly drawings, overall dimensions, labeled photographs)

• functional properties (e.g. state diagrams, connectivity, information flow, sequences)

Lengthy details, part drawings, source code should go in an appendix (with explicit forward reference). By reading the design specifications, one should be able to recreate something close to your design.

Tip: For the Winter quarter, this section should include your Functional System Prototype at the very least. FUNK-tional and Dark Horse prototypes may also be included if they are relevant, else put them in Development.

5. Project Management (What was done, why was it done, and how were resources allocated to the activity?)

• Review the winter quarter.

  • Is there enough detail to piece together how the team spent its time and resources?

    • Were they on track? (Can you tell?) -- It would be particularly interesting to see how the Winter Quarter Plan was followed or deviated from, and why.

  • Budgets: how were your limited available financial resources tracked and managed?

    • Describe any methods your team employed to achieve efficiency (e.g. shipping costs, borrowing versus buying) 

• Lay out a plan for spring. Make sure your total team reaches consensus on this. 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 spring SGMs.

  • What will your team do next? When & how will milestones be accomplished, and by whom?

  • How will the budget be spent?

  • Any lessons learned from your time management this quarter?

  • How will you meet the final deadline of EXPE?

6. References (From whom or where did you acquire needed knowledge?)

• Are the citations complete enough for the reader to track down the sources if she wants to?

• Are all sources of quotes, assertions (e.g. about needs or benchmarking claims) and figures taken from other sources properly cited with references?

7. Team Profiles and Reflections

• Who are the Stanford and Global teams that wrote/edited this final document and what are their reflections?

• Learning and Un-Learning are a duality. What assumptions did you need to remove?
  A useful reference: Why the Problem with Learning Is Unlearning

8. Appendices (Are your data and back-up information in the appendices?)

• Is there useful information in the Appendices or is it stuff that's not worth saving?

Deliverables

• Upload a PDF version of you Winter Documentation to the ME310 Box space: Winter Document

• Please remember to follow the file name format!

Remember...

• Tell a good story. It may not be the best idea to write the documentation by assignments or even chronological order. Think of what the most logical transition is. A lot of liaisons don't know / won't understand / don't care about the difference between funKtional and funCtional.

• Some sections are significantly longer than others. If you split up the work by sections, you will have some people doing more work than others.

• Proof-read. Make sure that all pictures look right. Make sure that no text requires magnifying glasses (happens a lot with excel charts and tables). Take into consideration the possible extra time required to proof-read sections from your global teammates.

• Embed material from the fall quarter into your documentation if it is still applicable to your project. If the material has become irrelevant to your current design direction, store it in the appendices.