How to Document

In this course, you are largely evaluated through the documentation you provide about your learning. Documentation is the process of writing down what you did over the course of making something, what you learned, what worked and what did not, and how to replicate your process.

You do not document tutorials. Those are signed off in class, and once you
are signed off you move on. You can mention tutorials in a project page if you
actually used it to build that project.

Structure Your Page with the Engineering Design Process#

Your log should tell the story of the project from beginning to end. Another person should be able to read it and understand the journey: the initial idea, the challenges faced, the solutions found, and the final outcome, and most importantly: how to make it themselves.

The Engineering Design Process (EDP) gives your story its structure. Every project in this course runs on the same six steps: Define, Brainstorm, Plan, Prototype, Test and Iterate. One trip through all six is a cycle. Your project page should show each cycle you went through, with each step clearly labelled, so your reader can follow how your thinking changed from one attempt to the next. A good project uses at least 2 of these full cycles.

Where do you start?#

Before you open any software or pick up any tools, figure out which of these describes you.

You already know what you want to make. Great. You have already done most of the Define step in your head, so write it down in a few sentences (what it is, who it is for, what it needs to do) and move straight to Brainstorm. Your brainstorm is not about what to make, it is about how to make it. What are the different ways you could build this object with the tools and materials available?

You do not know what to make yet. Start at Define. Look for a minor problem around you that you could design a solution for. Did something small break? Is there something on your desk, in your bag or at home that is annoying to use? Is there an object you could improve with a 3D printed part or a vinyl sticker? Keep it small. Once you have a problem, work through the rest of the steps in order.

Either way, the start of your page should make it clear which situation you were in and why you chose the project you did.

Your first cycle#

The first cycle is where you get from an idea to a first working version, often called a minimum viable product (MVP). An MVP is the simplest version of your object that does its main job. It does not need to look good or be finished. It needs to be something you can test, it does not need to be pretty.

For each step, here is what your reader should see on your page.

1. Define#

What were you asked to do, and what problem are you solving? One or two sentences in your own words. Then list the constraints you are working within (time, materials, size, your own CAD skills) and describe what a successful outcome looks like.

2. Brainstorm#

Show more than one idea. Include sketches (a photo of a page in your notebook is fine), links to things you researched, and existing products or designs that do something similar. Finish the section by stating which idea you are going with and why you picked it over the others.

3. Plan#

Break your project down into the smallest possible parts. “Make a phone stand” is not a plan. “Measure the phone with calipers, sketch the side profile, model the base in TinkerCAD, model the lip that holds the phone, print a test of just the lip, cut the vinyl logo” is a plan.

Then lay out what each day of work looks like. Which parts will you finish in which class? What do you need to measure before you can model? What has to be printed before something else can be cut? Include your drawings, measurements and a list of materials.

4. Prototype#

This is the bulk of your work and should be the longest section on your page. Modelling in CAD, slicing, printing, cutting, assembling: all of it goes here. Write the steps you actually took, in order, including the mistakes. Your reader should be able to follow this section, like you would follow one of the tutorials on this website, to build your MVP themselves.

5. Test#

Put your MVP to use and look at it critically. Does it do the job you defined in step 1? What works? What is “off” about it? Measure it, try it in the situation it was designed for, and compare it to your plan.

The goal of testing is not to prove your design works. The goal is to find out what needs to change and what this attempt taught you.

6. Iterate#

Summarize what you learned from testing and decide what the next version needs to fix or improve. List the problems in order of importance. This list becomes the starting point for your next cycle.

Your next cycle starts at Define#

Once you have iterated, you go around again. Your second cycle starts at Define, but this time you are not defining the whole project. You are defining the problems you ran into in the first cycle.

For example: “The phone slides off the stand because the lip is only 3 mm tall and the angle is too steep.” That is a new, smaller problem. Brainstorm ways to fix it (a taller lip, a shallower angle, a rubber pad), plan the change, prototype the new version, test it against the old one, and iterate again.

Each cycle should get its own clearly labelled section on your page (for example, Cycle 1, Cycle 2, Cycle 3) so your reader can compare versions side by side. Check your project’s rubric for how many cycles are expected.

The steps do not have to go in order#

The diagram shows the steps in a circle, but real projects rarely move around it cleanly. You will often jump back:

• Halfway through prototyping, you realize a measurement in your plan was wrong. You go back to Plan, re-measure, and return to Prototype.
• Testing shows your idea cannot work at all with the materials available. You go back to Brainstorm for a different approach.
• While planning, you find out your problem is bigger than you thought. You go back to Define and narrow it down.

Document the steps in the order you actually did them. If you went from Prototype back to Plan, your page should show that, with a sentence explaining why. Backtracking is not a sign that you did something wrong. Showing it is evidence of your problem solving.

Most objects are made of more than one part, and those parts rarely need the same amount of work. Treat each part (or sub-system) as its own small project that can go through its own mini cycles inside your larger cycle.

For example, a phone stand might have a base, a hinge and a vinyl label. The base might work on the first print. The hinge might take four small test prints to get the fit right. The label might need two cuts. On your page, the Prototype and Test steps of that cycle could contain a subsection for each sub-system, and the hinge subsection could show its own four quick Define, Prototype, Test loops.

Be thoughtful about your problem solving#

Iterating is not just “try again and hope.” Each cycle should be based on a specific observation about what went wrong and a specific idea about why.

To do that, you need the vocabulary to describe what is “off” about your design. Compare these two test notes:

• “The lid doesn’t fit.”
• “The lid is too tight. The inner lip is 0.2 mm smaller than the box opening, but the print’s layer lines add roughness, so I need about 0.4 mm of clearance instead.”

The second note tells you exactly what to change next.

Every cycle you complete exposes you to another problem and another solution. The more you iterate, the more solutions you have seen, and the faster you will recognize and fix the same problem on your next project. That practice is what your documentation is evidence of.

Wrap up: What you learned#

This section will go at the very top of your page once you’re done, but it’s actually the last thing you will complete! This wrap up section should be one paragraph to consolidate your project, show it off, and present your learning for your reader. This will be the first thing your reader sees when they get to your page, so tell us what it is, summarize what you learned to make it, and anything you think would be important to include.

What Should NOT Be Documented#

1. Instructions or documentation from another source.

   Your documentation is meant to be from your voice. If you referenced another tutorial or source online to complete your work, that’s great! You should link it to your page, but then also make sure you take the time to write down the steps you took to complete your work.

2. Documentation written by a partner or a group member.

   You will be asked to work with others in this class, and it’s true that your peers will be contributing work that you are not fully involved in. However, you shouldn’t be adding documentation about how something was completed by someone other than you. Instead, link to your peer’s documentation pages, describing the specifics (briefly, in a sentence) of what was completed by them.

3. AI-generated documentation

   You will be allowed, and even encouraged, to use AI in the course to help you complete and create projects. However, the line is drawn at documentation. Everything written on your page should be written 100% by you. This is because these documents are evidence of your learning, not an LLM’s learning. It is essential to practice communicating your understanding, even if you think it is not great at first. AI should not be part of any part of your documentation writing process, including editing. You may ask AI to review what you’ve written to check to see if you have left anything important out, but you need to specifically prompt your LLM to not provide you with what you should write.

4. Interruptions

   There will be moments in the class that we are pulled away from our work (fire drills, assemblies, power outages, etc.). These do not need to be included in your documentation unless they provide something meaningful to describing your understanding.

Write it as you go#

The last few minutes of most periods are for cleaning up and for documenting. The best habit you can get into is taking pictures throughout your work period, and jotting down one line every so often on what you just did. Note what broke, what iterations and changes you made, and what is next.

Example Documentation#

Mr. Mills’ Micro:bit Holder