Module 1 - Project management and documentation#

The goal of this unit is to learn

  • some easy but powerful tools to write better documentation and share it using version control systems.
  • some tips for successful Project Management

More specifically, here I will describe the steps necessary to create my website’s introduction page, along with all the utilities used, like git,mkdocs, comandline, gimp or GraphicsMagick, so that each of you has the necessary information to accomplish something similar.

Documentation#

1.1 Something you need to know#

It is worth mentioning that all manipulations are done in the MacOs operating system, so if you use Windows or Linux, there may be slight differences between the commands.

The website is written in markdown and converted to HTML format by mkdocs. All the necessary files are on the GitLab website in the fablab ULB documentation space, which we will have access to once we create an account. So to extract these files and constantly modify them, while also having the possibility to track changes and access internal versions, we will use the version control system git, we will talk about this in more detail later.

1.2 First steps - creating a GitLab account#

First of all, in order to access and modify the necessary files, we need to create a GitLab account. After logging in, we received access to the ULB fablab space, giving the professor our user id. Being on the main page, follow the steps below to find the user id.

Click on Edit profile

and in the Profile section the User ID is displayed.

1.3 SSH keys#

To be able to communicate with gitlab from our computer, we need to associate an SSH key. For me it wasn’t anything complicated, considering I’ve done this before, but for someone who is facing this for the first time, here’s a useful link SSH keys.

For start, looking back at the previous section, after accessing Edit profile, we click on SSH Keys.

Now we are in the right place to add the ssh key

1.3.1 How to create the SSH key#

Before you create a key pair, see if a key pair already exists.

  1. Open the terminal with ctr + alt +t
  2. Go to your home directory.
  3. Go to the .ssh/ subdirectory. If the subdirectory doesn’t exist, you need to generate the ssh key.
  4. If the subdirectory is present, use the command ls to check the files and see if you have a ssh key.

I did not have one on this machine, so I will show you how I created it. Once the terminal is open, you need to use this command ssh-keygen -t rsa -b 4096 -C "example@mail.com" with the email address used to create the GitLab account. To recover the created ssh key, being in the main directory, we access the .ssh subdirectory and use the command cat id_rsa.pub. The key will be displayed in the terminal, press ctrl + c to copy it and return to the GitLab website in the SSH keys section.

As you can see, in the area highlighted in red we paste our key and we confirm by pressing the Add key button. Here we go, the ssh key is created and connected to our GitLab account.

1.4 Git and other tools#

1.4.1 Git install#

To clone the gitlab repository, we must have git, it may already be pre-installed, to check, in the terminal we use the command git --version . If the git command is not recognized, then git needs to be installed. To install git I use homebrew. Using the link you can install it if you don’t have it already. So in the terminal type brew git install and now the git is installed on your machine.

1.4.2 Clone GitLab repository#

To clone the repository, on our personal project page, we click on Code and copy the link from the section highlighted in red.

Now , we need to open the terminal and go to the place where we desire that our project folder will be located. Using mkdir file_name we create the file, and access it with cd file_name/. Further, we use git clone Repository_URL to clone our repository. That’s it, our GitLab repository is cloned and we can access the files in the created folder.

1.4.3 Modify files#

To modify the files, we need a text editor. I use Visual Studio Code, an IDE that I am familiar with, and which I have often used to write code during my studies.It is my choice, due to its performance and the very useful extensions it has. You can download it using this link VSCode. It’s simple, you open your project folder in VSCode and you can start your work. A useful extension for this course is Markdown Preview Enhanced, that give us the possibility to preview our created page during our work.

1.4.4 Git commands#

After certain changes in the local repository have been made, it is necessary to upload them to the remote repository on GitLab. To do this we need to open the terminal and go to the subdirectory where our repository is located. With the git status command we can see the modified files, if there are any, or see if our local branch is up to date to the remote branch. After that we use git add . to mark all the modified files for the commit, or we can use git add file_name to add only a specified file. Further we do git commit -m "Commit Message" and finally git push to upload the changes to GitLab repository. We also don’t need to forgot about git pull. When we work in group on the same remote repository, it’s useful to use this command every time before we start to work, because this will update our local branch with the new changes made by someone else.

1.4.5 Mkdocs#

Before I discovered the markdown extension present in Visual Studio Code, I used Mkdocs package to launch my page and view it. To install it i used also Homebrew with the command brew install mkdocs , but if you have python on your machine you can install it using pip install mkdocs. Now, once Mkdocs is installed , in terminal, we need to be located in the folder where our file mkdocs.yml is present and we use the command mkdocs serve. Now it needs to give us a local link to our created page, as we can see below, we copy that link an we acces it in the browser. As a result, we can have a look at our site, constantly check the results and improve it.

1.4.6 Pictures#

For our web page, we often need images, that’s why certain tools are needed to modify them. It should be mentioned that in order for them not to be very big in size, it is necessary to crop them, to change their size. For this we can use the GraphicsMagick package or the GIMP program. Here you can find a useful link to learn how you can modify your images in GIMP .

I use both,GIMP offers a lot of tools to modify and also edit your pictures, but sometimes you need something simple and fast like GraphicsMagiks, that you can use in your terminal. Often I used it for resizing images with the comand gm convert -resize 600x600 bigimage.png smallimage.jpg that will resize bigimage.png without modifying the aspect ratio inside a bounding box of 600x600 pixels and convert it into .jpg . In the same time the command gm convert +append -geometry x400 image1.png image2.png image3.png image4.png strip.png was useful to compose a strip of images.

1.5 Project Management#

Within this module, we accumulated useful tips for successful Project Management. This will help a lot not only during this project, but also it’s a valuable practice for anyone who wants to be organized, deliver on time, not be pressured and be able to offer the highest possible efficiency and performance. I will try my best to avoid the 2 mistakes that people make when managing time:

  • The first one is thinking about it as a continuous, infinite line, whose duration is relative.
  • The second mistake is overestimating time. We tend to think, given a deadline, that we have plenty of time to finish a task. This is a big mistake.

During this project I will document my work incrementally from the beginning, rather than wait until the project is finished to start. This is called As-You-Work Documentation.

1.5.1 ChatGPT#

At the moment, I’ve only used ChatGPT to learn more about different commands available in Markdown and GraphicsMagiks.