Journals & Documentation

You are expected to keep an online journal of your progress.  Your instructors read your journals regularly to see how you are progressing, so you should update your journal regularly throughout the semester. At a minimum, we expect  you to summarize any insights you have in each week’s lab assignments, to discuss to the readings, and to document your production projects and technical research thoroughly.

Please make sure your blog assignments are online the night before class (by 8 PM EDT, GMT-4) so that your instructors and classmates can read them before class.

Good documentation habits

Document your projects thoroughly as you go; don’t put it off until the end.

Documentation Platform

You may document your major projects in a separate individual or group site if you choose, but you will be expected to link your site to the your class page on this site. Please avoid formats that are not text-searchable, as they won’t show up on search engines for others to use.

Blogs are great for documenting your process, as they’re usually organized in reverse chronological order. Once you’ve finished a project, however, set up a separate page or pages to summarize your projects when they’re done, so you can use this as a link in your portfolio.

Documenting Process

Good documentation should include a description and illustration of your project. Use pictures, drawings, and videos liberally to explain your work, although images alone usually don’t tell the whole story. Hence, you should include what it looks like, what it does, what the user or participant does in response. When it’s interactive, mention and show what the user does. Your explanation should give enough information that someone who’s never seen the project can  understand it.

You should also include a section describing how the project works, aimed at a more informed reader (your instructor, or next year’s classmates). Include a system diagram to make clear what the major components of the system are and how they communicate.

Another important part is to include what didn’t work and what you struggled with. Describe in words your questions and things you don’t understand so you can bring up during class meetings or office hours.

Documenting Code

Make sure any code that you post is well-commented, so you and others can understand what it does. Don’t overload your notes with code.  Code repositories like gitHub are best for sharing code, rather than blogs, so post your code to a repository and link to it from your blog.

If you are posting snippets of your code on your blog for quoting them in your post, refrain yourself rom adding screenshots of the IDE since it is not searchable and has a bad readability. Instead, cut and paste the code snippet or serial output on the IDE that you are referring to. Many blog platforms have features for posting code.

Documenting Circuits

Good documentation of circuits can help you communicate your circuit issues during class times and office hours efficiently. It’ll also become a useful reference for other classmates and yourself in the future. Uploading a picture of video of the breadboard itself does not guarantee a good readability of your circuits. Try drawing a diagram of your circuits either with your hands or on screen. The drawing process will help you understand your circuit better while producing a better documentation. You can also consider use circuit drawing software such as Fritzing.

Crediting Others

Make sure to cite sources from which you get your ideas, code, circuits, and construction techniques. When you base your work on someone else’s, cite the original author and link to their work, just as you would when quoting another author in a paper. If you only changed one part of an existing program, post only the part you changed, and link to the original. Copying code or techniques without attribution is plagiarism.  Few ideas come out of the blue, and your readers can learn a lot from the sources from which you learned and by which you were were inspired. So be generous in sharing your sources.

This also applies to AI tools such as Chat GPT. Since understanding basic techniques and concepts in physical computing is an important goal of this class, you are not encouraged to use Chat GPT in your assignments, otherwise instructed by your instructor. If you used AI tools for any reasons, make sure to document your step-by-step process thoroughly on how you used the tool, which part is from an AI tool, and what modifications you made. Also, demonstrate your own understanding of the code, which is the most important in the end.

Some good project summary sites

  • .tweenbots by Kacie Kinzer
  • fireLight By Tom Gerhardt. Simple project, doesn’t need a lot to introduce it.
  • Nice project materials in FRSK04 by Sam Lavigne and Fletcher Bach
  • Nuntinee Tansriraskul’s Shadow through Time foregrounds the project itself, describing and showing the final device first, and then summarizing the components and the process.
  • Matt Richardson’s  final project is documented nicely.

A few good journals on process