Fab Academy Documentation: Purpose, Technique & Tools

• Authors: Rico Kanthatham, Georg Tremmel
• Created: 1/30/2020, Last Updated: 1/18/2023

Documentation is not simply taking notes.

Think of Fab Academy documentation as the creation of your own web-based information reference pages, like making a Wikipedia entry. It needs to be informative to you and others who will read your documentation…so should be thoughtfully created.**

Purpose:

“Documentation” in FabAcademy serves several important purposes.

1. A permanent record of your own work and techniques. Your own documentation will be an important personal reference source for you in future. During Fab Academy you will be given knowledge at a VERY fast pace, therefore making a good record of techniques and procedures that you learn is critically important. If you don’t record your learning…you WILL forget. Expect to revise your documentation again and again…to make it better and more understandable (for you and others).

2. Evidence for Fab Academy graduation evaluation. Your documentation will be used by Fab Academy Local and Global Evaluators as proof of your assignment completion. In addition to text and images showing how you completed each assignment, you will also be required to include links to ALL working files and code used to complete the assignment.

   Very Important Note

   Copying the work of other people without crediting the original author is plagerism…and a violation of your Student Agreement, and will result in you disqualification from graduation

3. Experience Sharing”. Fab Academy is a globally collaborative effort and sharing is a core principal of Fablabs. The documentation you create will be read not only by you…but will certainly be looked at by other people to learn as well. It is highly encouraged that Fab Academy students around the world refer to each other’s (and past students’) documentation…reading about challenges and great solutions, success and failures in processes…and benefit from the experience of others.

Some excellent examples of documentation by past FA students as follows:

• Pamela Arana/Shanghai
• Kae Nagano/Kamakura
• Elena Cardiel

…take some time to read through their weekly assignment pages to get an idea of great documentation.

Techniques:

Note

Because “Documentation” is very important to Fab Academy graduation, it should be done with great care and attention.

Write with the aim to be clear, honest and detailed. Write with the thought that it should be easily understandable by you and others as well. Write in a style that is the most comfortable and speedy for you. Also aim to create documentation that is interesting to read by you and others. It is highly recommended that you look at example of great documentation of past FA students.

“Documentation” should be written in the most efficient way possible (time is limited). Some tips on efficient documentation as follows…

• Have a A5 notebook and pen with you at all times. While most of your documentation will be done with digital tools (laptops, mobile phones, tablets, etc.), a simple small notebook and pen is indispensable for jotting down quick notes, making a diagram or listing/organizing your soldering projects. You will surely fill one or more of these notebooks during the Fab Academy course.

• Document as you work. During your Fab Academy local work sessions, write quick notes (in your notebook, laptop, etc.) and take photos of working techniques or assignment progress (using your smartphone, PC screenshot, etc.) FREQUENTLY and CONTINUOUSLY. Don’t wait until you are finish with your assignment to start documentation (you will regret it if you do). The more quick notes that you make and in-progress photos/videos that you record…the faster and more complete your weekly documentation can be done. It is important that you documentation includes both successful work and failed attempts during your assignment sessions…because FA evaluators will want to see evidence of your process, how you approached and completed your assignment. Also, recording failed attempts will help you (and others) solve the same problem again when they reoccur (and they WILL reoccur!).

• Use Markdown to document your work for Fab Academy. Markdown text documents will be automatically turned into your personal webpages by the FA central coordination. While you have the choice to make your own webpages using sophisticated techniques like HTML5 or CSS…these techniques take more time than Markdown to generate documentation. Since time for Fab Academy students will never seem to be enough and should be efficiently applied to learning, fabricating and documenting…making a beautiful webpage should be a lower priority. (My opinion…) The basic aim of documentation is effective and informative communication…not beautiful webpages. Use your extra time to research and do assignment work instead.

• Write as bullet points first, then edit later into beautiful sentences and paragraphs. It is not a good idea to have all your final documentation be in bullet point format. It is not interesting to read. But having completed documentation in “ugly” bullet point format is better than having incomplete or no documentation at all. Write in a style that is comfortable for you…the idea is to create good, intelligent content that you and others can understand. Try to be fast and concise…not too little, not too much (write in you home language first…then translate into English later??). Documentation is communication first, style second. And done is better than perfect.

• Use great images in your documentation. An old saying goes…”a picture speak a thousand words”. A strong image can sometimes be used to replace many words. Images (and short videos) also makes documentation more interesting to read and easily understood. Learn to use a photo-editing programs to enhance images by adding text, arrows and boxes on top of images to make it even stronger and easier to understand.

• Very Important!!!! Batch process image files to reduce their size. Each image file uploaded to the FA cloud server should not be bigger than a maximum 200kb each. The maximum upload is 10MB. At the end of your Fab Academy course, your personal “Cloud Repository” should not exceed 500GB. Modern mobile phones tends to shoot high quality images that can be 1-2MB each. This size is unnecessary to display on a webpage. To keep image file sizes small enough, use a program such as XnConvert to batch process all your images for each week down to an acceptable size.

• Save often as you write your documentation!!!! I repeat…save your work often…or you will regret it!!! There is nothing worst than losing documentation work because of some accident (power outage, accidental deletion, etc.). Save your documentation every minute (CTRL + S or CMD +S…takes a half a second to do). Having to rewrite documentation is a painful waste of time…and you do not have time to waste.

• Create logical and sensible organizing sub-folders to save your files.. Within the “docs” folder of your Fab Academy “Local Repository”, you should have separate sub-folders for…Markdown documents (named Week1.md, Week2.md, etc.), Images (with sub-sub-folders called week1, week2,etc. in which each image should be named week101, week102, week103, etc.), Project files (with sub-sub-folders for each week in which sub-sub-sub folders each major program should be made…Eagle, Fusion360, Arduino, etc.). Being disciplined about identify files by the week that they belong to will be very helpful later in the course when you have hundreds of files to search through. Being organized will save you time.

Documentation Basic Template

The following recommendation will help you to generate “Bare Minimum” documentation that will be easy for Local and Global Evaluators to review (making your graduation approval at the end faster!). Weekly documentation pages should have the following components

1. Weekly Brief Summary. Write 2-3 sentences at the beginning of the page to recap your assignment completion experience for the week.

2. Weekly Assignment Requirement. List all the tasks that are required to be completed for the week. Do this to help you to understand exactly what you need to do for the week. The weekly assignment requirements are published by Fab Academy and is defines very specific items that MUST be done for the assignment to be considered complete by evaluators.

3. Group Assignment Link. This is a required feature of every weekly assignment page that evaluators will look for. Insert a hyperlink to the Group Assignment page for the same week.

4. Assignment Work Planning (SSTM). If possible, based on the list of required tasks…outline your strategy to complete all the tasks in the available time for the week. While this is not necessary, it will help you to get into the habit of applying Supply-Side Time Management techniques to your Fab Academy workflow.

5. Description of Assignment Work. Using text, photos, video…describe in reasonable detail your entire process for completing the weekly assignment. It is especially important to evaluators for you to describe your difficulties AND failures…and how you successfully overcame them. In some weeks, you will learn specific, step-by-step procedure to complete a task…in this case, using text AND photos…record the procedure in great detail. You will likely refer back to these procedural notes again and again during your Fab Academy course. Make it good and easy to understand (like a recipe for cooking).

6. Description of Important Weekly Learning Outcome. While not necessarily required, it may be useful to you and certainly useful to evaluators…for you to end your weekly documentation with a description of something important or particularly interesting that you learned in that week. Or make some comment about some additional work you would like to do later.

7. Links to Files and Code. This is a required feature of every weekly assignment page that evaluators will look for. Put all of them in one place at the end of your weekly documentation to make it easier for evaluators to find them.

8. Appendix. A highly recommended section for your documentation where you should put notes or links to research you did during the week to overcome your own knowledge deficiency and enable you to complete the assignment. It should be something that you might want to refer back to later when you need to be reminded.