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.

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.

Good documentation should include a description and illustration of your project. 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.

Use pictures, drawings, and videos liberally to explain your work.

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.

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.

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