1. Project management and documentation#

The purpose of this module is to learn some principles that help to manage a project and to developp a efficient workflow of documentation.

1.2 Project management advices#

The 2 important project management principles that caught my attention and that I will apply :

  • As-You-Work documentation : documenting continuously to not get overwhelmed by doing it in a too short amount of time and to not forget what we just did.

  • Spiral Development : making a list of priorities for each modules and trying to do the tasks following this established list.

1.3 Building the workflow of documentation#

1.3.1 Git and SSH key#

1) Install Git here and configure it : it was already installed on my computer.

2) Set up a secure way of connecting the local computer to the remote server using an SSH key by following this tutorial.

3) Clone a working copy of a remote project on your computer using the secured way following this tutorial.

4) Work on your remote working copy and sychronize with the remote server using these commands :

  • To update new changes done in the remote server on the local computer
    git pull
  • To update the new changes done in local computer to remote server
    git add -A
    git commit -m "COMMENT TO DESCRIBE THE INTENTION OF THE COMMIT"
    git push

1.3.2 Markdown#

The language we will use to format the documentation as a webpage is in Markdown. The text editor I have chosen is NotePad++. I have learned the basics of Markdown by following this tutorial.

1.3.3 Generating a website#

To visualize the .md files as a generated website I am using Mkdocs which allows me to create a website link using the command mkdocs serve.

I work with my NotePad++ text editor and the generated website side by side while documenting to see the results in real-time.

Everytime I add something in my documentation, I simply save the file using ctrl + S and the website automatically refreshes.

1.3.4 Image treatment#

To compress and edit images, I use the default photo editor of Windows.

If I want to add red lines to highlight something, I switch to edit mode, where I can do so, as shown in the following picture:

efore inserting images into my Markdown editor, I compress them to avoid overloading the servers with unnecessarily high quality. The photo editor includes a section for this purpose, as shown below:

Then, I adjust the quality to reduce the image size to around 100 KB:

1.3.5 ChatGPT#

Throughout this documentation, I will use ChatGPT as a supportive tool for two purposes:

  • English corrections : indeed my english being not quite good, I will use it exclusively to review the texts I write myself.
  • Technical questions : I will consult ChatGPT as a guidance on programming language such as Markdown, OpenSCAD, etc.

I will limit my use of ChatGPT to these two so that I can ensure the documentation remains my own work.