{"id":4823,"date":"2018-08-16T15:15:35","date_gmt":"2018-08-16T19:15:35","guid":{"rendered":"https:\/\/itp.nyu.edu\/physcomp\/?page_id=4823"},"modified":"2025-08-31T22:46:47","modified_gmt":"2025-09-01T02:46:47","slug":"journals-documentation","status":"publish","type":"page","link":"https:\/\/itp.nyu.edu\/physcomp\/journals-documentation\/","title":{"rendered":"Journals & Documentation"},"content":{"rendered":"\n

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\u2019s lab assignments, to discuss to the readings, and to document your production projects and technical research thoroughly.<\/p>\n\n\n\n

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.<\/span><\/strong><\/p>\n\n\n\n

<\/span>Good documentation habits<\/span><\/span><\/h2>\n\n\n\n

Document your projects thoroughly as you go; don\u2019t put it off until the end.<\/p>\n\n\n\n

<\/span>Documentation Platform<\/span><\/h3>\n\n\n\n

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\u2019t show up on search engines for others to use.<\/p>\n\n\n\n

Blogs are great for documenting your process, as they\u2019re usually organized in reverse chronological order. However, they’re not a succinct way to showcase the way once it’s done. When you finish a project set up a separate page or pages on your site to summarize the project, so you can use this as a link in your portfolio.<\/p>\n\n\n\n

<\/span>Documenting Process<\/span><\/h3>\n\n\n\n

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\u2019t 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\u2019s interactive, mention and show what the user does. Your explanation should give enough information that someone who\u2019s never seen the project can  understand it. <\/p>\n\n\n\n

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

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

<\/span>Documenting Code<\/span><\/h3>\n\n\n\n

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

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.<\/p>\n\n\n\n

<\/span>Documenting Circuits<\/span><\/h3>\n\n\n\n

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<\/a>.<\/p>\n\n\n\n

<\/span>Crediting Your Sources <\/span><\/h3>\n\n\n\n

Make sure to cite sources from which you get your ideas, code, circuits, and construction techniques. When you base your work on someone else\u2019s, 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.<\/p>\n\n\n\n

NYU offers access to and information on Zotero<\/a>, which is a great tool for managing citation. Here’s an intro video<\/a>. Zotero has a browser plugin that lets you save links to your account easily. You can generate collections of links like this<\/a> from the app. You can even automatically generate citations for any source from the app. You can download the app and the browser plugin<\/a> from this link. <\/p>\n\n\n\n

This also applies to AI tools such as Chat GPT. Read Use of AI Policy<\/a> for this class.<\/p>\n\n\n\n

<\/span>Some good project summary sites<\/span><\/h2>\n\n\n\n