1. Making a documentation#

Goals of this unit:

  • Setting up a git repository
    • Making an SSH Key
    • Git and commit
  • Making a website with mkdocs
    • Manipulation of images sizes
      • converting a video into a gif
    • introduction to markdown
  • project management

Environment#

The environment of this documentation is Linux. It means that all installation processes and terminal command will be made in a Linux environment.

Linux is an open source OS made by a wide community pursuing the ideal of FOSS. I recommend immutable distribution of Linux as it is pretty easy to repair in case of a problem. Here a nice distribution of Linux, the one I use.

git and GitLab#

The common word in GitLab, GitHub and others is the “git” word. git is a workflow controller, extremely powerful for teams (like teams of thousands of contributors) as well as teams of one person. It is a bit difficult to use at the beginning, but too useful to not make an effort.

install git#

Almost all Linux distro have git already installed. This will tell you what command to execute in the terminal according to your OS.

SSH#

To ensure security on communication between the servers of GitLab and the computer, GitLab uses SSH keys.

creating an SSH key#

Verifying if there is already an ssh key on the computer:

ssh-add -l

If there is not:

  1. Open your terminal.

  2. Generate the SSH key by typing in the following command, replacing “message” with a custom comment at the end of the public key, which usually is the email or identification of the creator of the key pair:

    bash ssh-keygen -t ed25519 -C "message" 3. Press Enter to accept the default file location (Home folder). 4. Enter a secure passphrase when prompted.

SSH Key#

  1. Start the ssh-agent in the background: Is the agent already running in the background? bash eval `ssh-agent` If a PID is given, no need for the next command: bash eval "$(ssh-agent -s)"
  2. Add your SSH private key to the ssh-agent: bash ssh-add ~/.ssh/"name of your key" The name can be the algorithm of the key (ex: ed25519)

ssh and GitLab#

To establish a connection between a server and the computer, the public version of an ssh key has to be shared.

On GitLab: profile picture → preference → SSH key.

In the correct field, fill in what this command respond.

cat /var/home/"username"/.ssh/"name_of_ssh_key".pub

And done! Normally, an ssh connection is established.

repository#

Each project on git is called a repository. For this course, we already have a repository to clone on the computer.

On the page of the repository, clone → copy with ssh key. In the terminal:

cd ~/"path to a folder in whitch the repo has to be"
git clone "what has been copied"

It will create a new folder who is the clone of what’s on GitLab

uploading changes#

Once some changes have been mad to the local repository, the command

git add --all
git commit -m "description of whats has been modified"
git push
  • Will add all the changes to the future commit.
  • commit with a synthesized comment describing the commit
  • push the commit online.

Documenting in mkdoc website#

The site of individual documentation of the course “How To Make (almost) Any Experiment Using Digital Fabrication” use mkdocs. Mkdocs use markdown.

markdown#

Markdown is really useful for writing anything with a simple layout. Similar to latex, markdown is much, much simpler than latex and can be read easily without rendering.

Any treatment text editor can do the work. Somme, with markdown capability like apostrophe, obsidian, vscode can give a preview of the formatted view.

This cheat sheet is to keep at the beginning to familiarize yourself with markdown. On the beginning, only title, tables and super-link are useful.

result syntax
title # header 1, ## header 2,...
list * first elem *second elem
images ![caption](url or file location)
URL or local file [caption](url or location)

Images compression#

To save space on the repository, a solution is to reduce the space taken by images. It can be lousy or lossless. All software can do the work.

Image compressors with GUI#

Curtail is a flatpak application I will be using for this docuementation. There are, of course, many software like this.

ImageMagick#

A solution without GUI is ImageMagick

Installing#
```bash
sudo apt install -y ImageMagick
```
Using ImageMagick#

  1. To convert an image from one format to another, use the convert command. For example, to convert a JPEG image to PNG: bash convert image.jpg image.png

  2. To resize an image, use the resize option. For example, to resize an image to a width of 200 pixels: bash convert image.jpg -resize 200 image_resized.jpg

  3. To crop an image, use the crop option. For example, to crop an image to 200x200 pixels in the top-left corner: bash convert image.jpg -crop 200x200+0+0 image_cropped.jpg

Remember to replace image.jpg and image.png with your actual image file names.

GIF#

GIF stand for Graphics Interchange Format. It will not always be lighter than a video format. Best is to test multiple format.

  1. Install FFmpeg, a powerful tool that can handle this task. You can install it using your distribution’s package manager. For example, on Ubuntu, you would use the following command:
sudo apt install ffmpeg
  1. Use the following command to convert the video to a GIF:
ffmpeg -i input.mp4 output.gif

Replace input.mp4 with the path to your video file, and output.gif with the path where you want to save the GIF.

running mkdocs#

sudo apt install pip mkdoks -y
pip install mkdocs-bootswatch

will install it and now the command in the folder with the “mkdocs.yml” file:

mkdocs serve

Will give a URL to copy and paste in a web browser to preview what the site will look like once uploaded to GitLab and the server.

Project management#

Projects take time. To maximize productivity, there exist many project management techniques. Some are described here.

Techniques#

  • Modular & Hierarchical Planning: This technique involves breaking down a project into smaller, modular components that are easier to complete. These components are arranged in a hierarchy of importance. For example, if you’re building a robot, you might break it down into sub-projects like the head, body, arms, and legs, and prioritize them accordingly.

  • Supply-Side Time Management: This technique involves organizing the project by time, not tasks. You divide your available work time into discrete segments, and then fill those segments with tasks to be completed for the week. This helps ensure that you can finish your assignments in the available time.

  • Spiral Development: This technique involves starting with a bare minimum version of the project, and then incrementally improving it with added features and refinements. This allows you to make progress and get feedback on the most important aspects of the project early on.

  • Parallel Development: This technique involves working on several project tasks in parallel, rather than one after another. This can help speed up project completion, especially when different tasks can be worked on independently.

  • Triage: This technique involves dynamically prioritizing critical tasks over non-critical tasks. This can help ensure that the most important parts of the project are completed first.

  • Bottom-up Debugging: This technique involves performing debugging on smaller, simpler component parts of a project, rather than on the entire, complex project. This can make it easier to find and fix problems.

  • As-You-Work Documentation: This technique involves documenting your work incrementally from the beginning, rather than waiting until the project is finished to start. This can make it easier to keep track of what you’ve done and share your progress with others.

Principles to keep in mind#

  • Parkinson’s Law: is a principle in project management that states “work expands so as to fill the time available for its completion”. This means that if you give a task a longer deadline, it will take longer to complete, even if it could have been completed more quickly. This is often due to inefficiencies or procrastination that creep in because of the perceived abundance of time. The law highlights the importance of setting appropriate and realistic deadlines to ensure efficient work.

  • Hofstadter’s Law is a principle in project management that states “It always takes longer than you expect, even when you take into account Hofstadter’s Law”. This law, coined by cognitive scientist Douglas Hofstadter, highlights the difficulty of accurately estimating the time it will take to complete tasks, especially complex ones. It suggests that even when we acknowledge this law and allocate extra time for a task, it may still take longer than expected. This law underscores the importance of building in buffers and contingencies when planning project timelines.

What I will use for this course#

For this course I will use the As-You-Work Documentation. Simply because we have a documentation to fill for each module and I have not experienced enough in what we will learn to make a assumption of the time each module will take.