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) 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 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:

A few good recent sample journals:

Originally written on August 16, 2018 by Tom Igoe
Last modified on August 28, 2018 by Tom Igoe