1. Project management and documentation#

This week’s work was to get used to the methods used for the documentation of our projects.

Existing Documentation#

VS Code#

Unfortunately for the Open Source world, I decided to continue using Visual Studio Code. I was already familiar with it and had added many modifications to make it an efficient workflow. Therefore, I did not want to change to a new IDE in which I would have to do all of that again.

Part of the project management aspect of the class is making an efficient workflow. So, I dedicaded some time to adjust the parameters and hotkeys of my VS Code to improve the experience of coding on Markdown. The most important one is adding a shortcut to open the preview of a Markdown file next to the “.md” file that is open.

Markdown#

The Markdown language was already familiar to me. This language is easier to use than HTML. So, the Markdown file will be translated into HTML by MKDocs. Many commands are really self-explanatory, such as: - creating lists and, - stylising words (_stylising_ **words**).

Some commands I did not know before, but have found useful, are listed below.

Command Description
![](image.jpg) Inserting images in Markdown.
[Useful Website](https://usefulwebsite.com) Links website on the words “Useful Website.”
`code` Using ` around a command shows Markdown code instead of replacing it with its intended effect.
<!--- comment block ---> How to comment a block.

In Markdown, you can also insert an image with HTML. Coming from LaTeX, this way of adding images to documents seems more natural to me, but in the long run, the Markdown version is easier and faster: 

  <img src="images/codebutton.png" alt="Code Button" width="60%" hspace="10" vspace="10">

In the end, this way of adding images did not work on the website. The images did not appear. So, I used the Markdown way:

![Code Button](images/mod1/codebutton.png)

GitLab#

GitLab allows you to edit your documentation locally and then upload it to the Fablab ULB GitLab.

Installing Git, SSH key, cloning the repository#

I already had Git installed on my computer, as I had used it in previous years for group-based programming projects. But, I still had to create a SSH key to securely communicate with the ULB Fablab GitLab repository where the website will be published. I chose the ED25519 key, which can be installed with this CLI command:

ssh-keygen -t ed25519 -C "<comment>"

with the comment being a way to identify this key’s functionality when handling multiple keys. Then, I added the key to my GitLab account. To do so, first I copied my key with the following command:

tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

I added the key to my GitLab account. This is necessary in order to authenticate your communication with GitLab when trying to clone the repository onto your computer. Then, I cloned the repository under my name in the ULB Fablab GitLab onto my computer to be able to access it from Visual Studio Code (VS Code). To do this I used the command:

git clone <project url>

with the “project url” being accessed from the project website on GitLab by clicking on the blue “Code button” as seen below.

Code Button

Uploading files#

There are two main ways I will use to upload files onto the ULB Gitlab. The idea for both is the same. First, at the beginning of each session, “pull” all changes onto my computer. Then, when I am done editing, I can “commit” my changes to save them and then “push” changes to upload them to the GitLab. On the Terminal app, this appears as running the commands:

git pull
git commit
git push

But I will not be commonly using these commands, seeing as I use VS Code and it has an intergrated way of doing these same actions. I am more used to doing it this way:

VS Code

This section of the VS Code IDE allows me to write a message associated with my commit and then commit the changes I have made. Then, I can pull and push changes with

Compressing images#

In order to keep the website fast and efficient, images will need to be a small as possible. To do this, I used built-in software on OSX. In Preview, there is an “Adjust Size” Tool that allows me to choose the resolution, and thus the size, of the image that I want to compress.

Compressing images

Project management#

The most important project management technique that I will be using is spiral development, in which I will focus on the larger picture and plans before going into details of the documentation. I have to focus on the larger picture instead of focusing on details that will hold me back from advancing.

I also will be taking notes and pictures every day, to continuously document my work. This is important to being able to accurately and efficiently document my experience in this class.