Tips & Tricks

Table of Contents

Handy hints when doing the FA.

  • every week neil links to featured assignments. check those!
  • peole with good documentation & learning from their mistakes:
  • Krisjanis: When documenting it is like painting a picture: think about the picture as already being there and you are just finishing it.
  • set up tracking page for final project!
    • for others to show your development. like a personal journal
  • MIT students can be seen [https://fab.cba.mit.edu]

Documentation Workflow

How I do my documentation.

Peparations (to be done once):

  • Fotos
    • smartphone
    • set up to name images after date and time
    • set up to take images of aspect ratio 4:3 (largest area, can be cropped afterwards) of a reasonably large size (so that the editing software does not take too long later on).
    • foto directory is set up to be synced with a directory of the same name on my laptop using syncthing
  • Screenshots
    • spectacle, set up to name images after date and time.
    • peek for capturing GIFs
  • Bookmark directories for camera, screenshots, website in the file browser for fast access.
  • Software for batch editing images:
    • using shotwell
    • choose hero shot and crop it

Procedure:

  1. Create a page for the current week’s documentation from a prepared template.
  2. Check reference documentations of 1 to 2 previous year’s students for the current week for orientation.
  3. Work, take notes, take fotos/screenshots.
    • For every step:
      1. Take picture/screenshot.
      2. Take a note.
  4. Refine pictures.
    • Import all pictures in Shotwell.
    • Go through all pictures: crop, edit, delete (the ones you do not need).
    • Export the pictures to the directory of the current week.
      • If needed, the pictures can be exported in subfolders corresponding to the subsection they will be used in. This makes it easier to find them later on.
      • Batch rescale + convert to jpg, 90% quality + exclude metadata.
    • Choose week’s title picture & crop that to 5:2 aspect ratio.
  5. Add pictures to the document at the location where they shall be.
    • Have a file browser open where you can browse the pictures. Check the picture you want to add, copy its name and paste it to the .md file.
  6. Refine notes to be prose from top to bottom.
    • Make use of Language Models. Be sure to document their use. Find example prompts below. Only use for small sections, do not edit a whole chapter in that way, it gets unhandy, since you cave to double check!
      1. Paste section along with respective prompt to LM.
      2. Paste output of LM to md, render, proofread
    • Italicize latin abbreviations: 
      1# vim commands
2:%s/ etc\. / _etc._ /g
3:%s/ i\.e\. / _i.e._ /g
4:%s/ e\.g\. / _e.g._ /g
    • Use aspell for spellchecking.
  7. Check file size before you push 
    1du -h

Prompts

Form bullet points to prose text. 

1Take the following bullet points and form prose text out of them. Do not add any additional information. Only use those words used in the bullet points and, additionally, those that are absolutely necessary to build grammatical sentences out of the bullet points. Formulate everything in past tense. Correct spelling mistakes:
2
3<insert bullet points>

Form bullet points to prose text where the bullet points have some structure. 

 1Take the following bullet points and form prose text out of them. Do not add any additional information. Only use those words used in the bullet points and, additionally, those that are absolutely necessary to build grammatical sentences out of the bullet points. Formulate everything in past tense. Correct spelling mistakes. Before I give you the bullet points, I would like to explain you their structure. The Bullet points are organized in the following way
 2
 3resource  1
 4- bullet point 1
 5    - bullet point 1.1
 6    - ...
 7- bullet point 2
 8- ...
 9
10resource 2
11- bullet point 1
12- bullet point 2
13- ...
14
15That means that I consulted several resources and took my notes for each. Formulate the aforementioned prose text so that it names which information came from which reference. Subdivide the text into the thematic sections <insert sections>:
16
17<insert bullet points>

Summarize Bullet points to text. 

1Summarize the following text in one paragraph:
2
3<insert text>

Refine bullet points. 

1Take the following bullet points and form grammatical and orthographically correct new bullet points out of them. Do not add any additional information. Only use those words and letters used in the original bullet points and, additionally, those that are absolutely necessary to build grammatical and orthographically correct new bullet points out of the original bullet points. Formulate everything in past tense. Correct spelling mistakes:
2
3<insert bullet points>

Fix tense, spelling and interpunctuation. 

 1Take the following text at the bottom and return it unchanged. You may change it, but only if it is necessary so it meets the requirements listed below and do not change under any circumstances the content inside a <highlight ...> ... </highlight> code block where ... is a substitute for arbitrary text and do not remove any curly brackets and do not consider valid markdown syntax as an mistakes and do not add line breaks yourself:
 2
 3Requirements listed below:
 4- The text is written from the perspective of "I".
 5- The text is in general written in past tense.
 6- The text is free of spelling and interpunctuation mistakes.
 7- The text is free of grammar mistakes.
 8
 9Text at the bottom:
10
11<insert text>
summarize longer texts: 
1Summarize the following text in one paragraph:
2
3<insert text>

Downloading VSCode Packages as VSIX Files

Scripts & Commands

batch converting & resizing 

1mogrify -resize 1000\> -format jpg -quality 90 *

batch compress 

 1#!/bin/bash
 2
 3for f in $(find . -type f -name '*.png' -o -name '*.jpg' -o -name '*.jpeg' | grep ./ | xargs realpath); do
 4    stem=$(echo "$f" | awk -F'.' '{print $1}');
 5    ending=$(echo "$f" | awk -F'.' '{print $2}');
 6    echo "$f";
 7    if [ $ending != "mp4" ]; then
 8        magick $f -resize 1000\> -quality 90 -format jpg $stem".jpg";
 9        exiftool -all= $stem".jpg"
10    fi 
11done
12
13find . -name "*.png" | xargs rm  
14find . -name "*_original" | xargs rm

 1#!/bin/bash
 2# pscrot - periodic screenshot
 3
 4
 5# Check if a command line argument is provided
 6if [ $# -gt 0 ]; then
 7    # Use the provided argument
 8    sleepsecs="$1"
 9else
10    # Use a default message if no argument is provided
11    sleepsecs=5
12fi
13
14echo "taking one screenshot every $sleepsecs seconds."
15
16while true
17do
18    scrot -f ~/Pictures/Screenshots/pscrot/$(date +%Y-%m-%d__%H-%M-%S).png
19    sleep $sleepsecs
20
21done

Cut video from start to end time. 

1ffmpeg -ss 00:01:00 -to 00:02:00 -i input.mp4 -c copy output.mp4

Create video from images. 

1ffmpeg -framerate 10 -pattern_type glob -i './*.jpg'  -c:v libx264 -c:a copy -shortest -r 30 -pix_fmt yuv420p raw.mp4

Major Pitfalls Regarding the File Size

  • read the general essentials
  • notes from julian (IT maintainer) on filesize
  • comments in chat where I asked what would be a good file size. answers:
    • 500MB max for the entire FA2025 course
    • about 10-20Mb a week
  • images
    • has changed over time
    • minimum is when you can’t see what it’s about
    • something between 900 and 1200 width
      • 1200px is quite big. Depends on how much detail you want to show.
      • Unless you need the detail, but then its better to focus and crop the image
    • image size depends on what you use them for. e.g. 820px for title pages is okay. for images that are displayed bigger, you can see if you save them as such
    • Filesize should not exceed 100/150Kb
    • on ferdi’s website all images are 950 images wide. 1200 is also ok
    • how to edit them?
      • it’s best if you take large photos and then downscale them with ffmpeg
      • 4:3 is quite nice as default then I can adjust.
        • if the photo is as high quality as possible, 90% is enough.
        • if i then want to downscale the stuff:
      • have little information in images! Otherwise, they might be large
    • post-processing: - 90% is ok. - should be small enough in most cases. - 950 width with 90% compression is a good guideline
    • throw out exif data, but sometimes this is also useful.
  • videos
  • 3d files:
    • not a problem, since these are mostly only text files (stl)
  • big file sizes are then 3d scanning week. but there it is saved somewhere else