Each of the three creative technical exploration projects have the same submission and documentation requirements, which are listed below. Documentation submissions are due through the course WordPress site.

This page has three sections: first, why you submit documentation, then what to submit for documentation, and finally how to submit it via WordPress.

Why do you submit documentation?

The Arduino project was born, after some twists and turns, out of an Italian masters student’s thesis.¹ He could have, one imagines, kept all those ideas to himself, started up a little factory, and sold them for €50 and called it a day. But the project has grown into a worldwide thing of beauty because the hardware designs (how to build an Arduino) and all of the underlying software (how to program one) are “open-sourced.” This means that anybody who wants to can see the community’s work and make their own version. Maybe even improve it themselves, and then suggest that their improvement might be something the community as a whole wants to adopt. Don’t believe me? Look at all these people contributing to the project’s Github page.

You’re submitting documentation for two audiences: to keep a record of what you’ve done for yourself, and to share a record of what you’ve done for others. You’ll want to get a job some day and having good pictures of projects you’ve built is only going to help. Think of how great it is for someone to see your cool project, get inspired, and build on it to make their own customized version. The answer is: very great! That’s why you do documentation.

What to submit (documentation content requirements)

If you have any questions about the submissions requirements, or run into technical problems, be sure to contact the instructor or TA before the due date.

Each documentation submission must consist of at least:

• Carefully- and well-shot images of the final project. Take these using IDeATe’s PhotoZone backdrop and lighting for an especially easy professional look, or shoot out in the field if you prefer. The DSLR photography guide provides a lot of pointers.
  At least three shots:
  1. Overall photo for proportion and scale
  2. Detail photo of any part that you’d like to highlight (up to 3)
  3. Images showing the use of the thing (up to 3)
  4. Optional—if it moves, gif or gifv or little .mov which will be embedded in the documentation page

• Simple narrative description of the thing and usual operation of the thing—the type of plain and straightforward description that you might write in a letter to a child to explain what you had made. Free of judgment and totally literal and straightforward. Try to use as little technical language as possible. (E.g. “A white plastic box has a switch on the top side. When the user turns it on, a green LED flashes five times showing that the system is ready. A small white flag waves back and forth.”) For a study in the art of using simple language, see Randall Munroe’s wonderful Up Goer Five. To use a simple-language filter yourself, try the Up-Goer Five text editor.

• Three progress images, each of which could be a step or misstep that happened along the developent process, and each with at least a sentence or two caption. These images may capture decision points, especially interesting or illustrative mistakes, or other mileposts along the way. The idea is that these medium-quality images (though good pictures work too) are taken along the way to document progress. Sometimes they will be understood as being moments-that-matter only in retrospect.

• Schematic, hand-drawn and scanned, or executed in software like Fritzing, EAGLE, in some flowchart application like draw.io, or any other way that produces a reasonably legible output. This should be done well enough that a competent person, reading the drawing and with the appropriate parts, could recreate the electrical system of the project.

• Code submission, embedded into the project page, and preferably with a Github or other version control service public-facing link. Include license text at the top of your code if you wish (i.e. copyright, CC BY-SA 4.0, the MIT License, release it to the public domain, or just follow your heart). If you have written code that you wish to keep strictly proprietary for any reason, please speak with the instructor about an exception to this documentation requirement.

• Discussion pertaining to process and outcome. For instance, what was easy, what was hard, what did you learn? What little tweak, in retrospect, would’ve changed the direction entirely? This is an opportunity for you to reflect on your creative and technical growth through the project, and think about what growth you want to aim for next. This shouldn’t be a recital of your process, but rather a meaningful reflection.

How to submit (WordPress instructions)

All documentation is submitted by making a post on the course WordPress site.

• For Project 1: Surprise, make a post with the title in the format “Surprise: Your Project’s Name Here.” Either group member’s account can be used to compose and publish the post, with the understanding that it’s a shared effort. On the right side of the page where you compose your post, under “Categories” select “Project 1.”

• Upload your images at a reasonably high resolution; 1000 pixels of width is the lower boundary of what you should aim for. After adding an image to the post, click on it in the editor, click on the pencil icon to get to its Image Details popup, and select Size: large.

• You can also use the Image Details menu to add a caption to an image.

• To add properly formatted code to your post:

  1. Paste your code into the editor,
  2. Add the tag [code language="C"] above the first line of code and the tag [/code] below the last line of code, and
  3. Select all of the code text and change its paragraph style to “Preformatted”

---

Footnotes: