1. Gestion de projet et documentation#

Bienvenue dans le premier module, celui qui t’apprendra les bases de la documentation.

Le but de ce module est d’apprendre les bases d’outils numériques puissants afin de pouvoir rédiger une bonne documentation.

Pour commencer il faut savoir que je suis sur Mac OS, c’est important que vous le sachiez car les logiciels ne sont pas exactement les mêmes que sur windows.

À quoi sert la documentation ?#

Le fait de documenter un travail sert en grande partie à se souvenir soi-même des étapes parcourues afin d’arriver à notre but. Mais aussi à informer d’autres personnes qui seraient intéressées de parcourir un chemin similaire au nôtre.

Ce n’est pas le résultat qui compte dans une bonne documentation, c’est le parcours pour y arriver qui est le plus important. C’est grâce à nos échecs et nos réussites qu’il est possible d’expliquer les meilleures méthodes à suivre ou à ne pas suivre.

2. La base des bases#

2.1 Le terminal#

N’ayant jamais travaillé avec un terminal, j’étais litéralement perdu en arrivant à ce cours. Pas de panique, c’est normal, je vais essayer de t’y introduire le mieux possible. Pour commencer, comme je suis sur Mac OS, je peux ouvrir mon terminal en appuyant sur Commande + Barre d’espace pour lancer Spotlight, puis saisir « Terminal » et double-cliquer sur le résultat. On vient d’ouvir une interface qui contrairement aux interfaces graphiquesn où l’on interagit avec des icônes et des menus, fonctionne principalement avec des commandes textuelles. Il suffit de taper des commandes, et le terminal les exécute.

Plusieurs commandes sont très utiles quand on débute. J’ai utilisé le tutoriel fablab mis à notre disposition afin d’apprendre les bases de la syntax.

Voici les commandes les plus utiles :#

ls : lister les dossiers et les sous dossiers

cd : Naviguer entre les dossiers, = changer de répertoire (suivi du chemin qu’on veut)

man : Pour appeler l’aide, diminutif de manual

pwd : Afin de se retrouver, affiche le chemin du filesystem

mkdir Pour créer un dépot

find Afin de retrouver des fichiers

2.2 Git#

J’ai mis du temps à comprendre ce qu’était Git. Pour faire simple, Git est une “espece” de platefrome permetant la collaboration entre plusieurs développeurs. Plusieurs personnes peuvent travailler sur le même projet en même temps, travailler hors ligne et effectuer des opérations sans avoir besoin d’un serveur central.

Dans la Fab Academy, nous travaillons avec des dépôts git . Chaque laboratoire dispose d’un dépôt git dans lequel les étudiants poussent leur travail et récupèrent le travail d’autres personnes. Ceci permet de tout centralisé et d’avoir accès aux travaux des autres. C’est entre autres pour ça que vous pouvez me lire. Pas mal non ?

2.2.1 Installer Git#

Pour instaler Git il faut d’abord installer une interface utilisateur en ligne de commande (CLI) afin d’établir une « communication » entre nous et l’ordinateur. Ça tombe bien, on sait maintenant ouvrir le terminal sur Mac. Pour télécharger Git j’ai d’abord besoin de munir mon Mac de homebrew ( Homebrew est un gestionnaire de paquets qui facilite l’installation, la mise à jour et la gestion des logiciels en ligne de commande).

Son installation est très simple, il suffit d’aller sur Homebrew, de copier la commande et de l’entrer dans le terminal.

Une fois fait, il est possible d’installer Git grace à la commande : brew install git

Mon mot de passe de Mac m’a alors été demandé, une fois celui-ci rempli Git est installé ! Pour vérifier qu’il est bien installé, j’entre la commande git - - version dans mon terminal.

2.2.2 Ma clé SSH#

Pour collaborer sur un projet commun, nous utilisons le serveur GitLab. Ce serveur nous permetra de partager nos projets sur lequels chacun poura contribuer. Pour travailler localement sur ce projet et ensuite envoyer les modifications sur le serveur, il est nécessaire de s’identifier. Cela se fait en générant une paire de clés SSH, celles-ci permettent de créer une connexion sécurisée entre mon ordinateur et le serveur de Gitlab. Dans cette paire l’une des clé est publique et sera par la suite ajoutée à notre compte Gitlab, l’autre est personnelle et sera à garder pour nous.

Avant de commencer la procédure pour générer cette paire de clé, il faut d’abord choisir quel type de clé utiliser. En suivant ce protocole, j’ai décidé d’utiliser la clé « ECDSA ».

Pour générer ma clé, j’ai ouvert mon terminal et introduit ceci ( en remplacant “exemple@ulb.be” par mon adresse mail ulb):

ssh-keygen -t ecdsa -C "exemple@ulb.be" -P "

Mon terminal à alors affiché ceci :

À la suite de cette commande, un dossier .ssh sera créé sur votre ordinateur. Dans mon cas, il n’était pas affiché (c’était une sorte de dossier fantôme). Pour le trouver, j’ai alors utilisé la commande find. Une fois trouvé, j’ai utilisé la commande cat pour lire le contenu du fichier nommé .ssh/id-ecdsa.pub, au sein duquel se trouve ma fameuse clé. Voici un aperçu de toutes les commandes à la suite :

Ça y est, je peux copier cette clé et aller la coller dans l’onglet Clés SSH sur Gitlab. Voici le chemin pour accéder à cet onglet : Paramètres utilisateur > Clés SSH

Ma clé est ajoutée, je vais pouvoir établir une connexion entre mon ordinateur et le serveur Gitlab.

2.2.3 Cloner le projet#

Une fois le protocole terminé, mon accès au serveur est sécurisé et je peux créer un clone. L’objectif de cette étape est de cloner un dépôt de fichiers, modifications, etc. (propres au projet, bien sûr ; le but n’est pas de cloner notre ordinateur) depuis notre ordinateur vers le serveur GitLab pour pouvoir travailler directement à partir de cuici-ci. C’est une étape à réaliser une fois par module.

Pour ce-faire, il faut d’abord ouvrir Gitlab. Ensuite, il faut suivre ce chemin : projet > Étudiants> Notre compte > Code > Cloner avec SSH!

Une fois l’URL copiée, je vais pouvoir l’utiliser dans mon terminal. D’abord, j’ouvre le dossier que je souhaite copier ( rappel : grâce à la commande cd). Une fois ce dossier ouvert, j’utilise la commande git clonedevant la copie de l’URL pour créer ma copie. Voici une photo du procédé :

2.3 Mettre à jour le transfert d’information#

Maintenant qu’une connexion est établie entre mon dossier lou.ferir et mon serveur git lab, je vais pouvoir travailler sur les fichiers de mon dossier et 2 fois par semaine, les modifications seront mis-à-jour automatiquement sur mon serveur gitlab. Pour qu’un transfert d’inforamtion puisse avoir lieu, après chaque changements effectués d’un l’un des dossiers, je dois effectuer ces commande dans mon terminal : | Commandes | Utilités | |-------------|------------| |cd |Change le répertoire actuel vers le dossier spécifié| |git pull | Récupère les modifications |effectuées du dépôt distant et les fusionne avec votre copie locale. |git add --all | Ajoute toutes les modifications (fichiers ajoutés, modifiés ou supprimés) dans le répertoire de travail à la zone de staging (staging area) de Git.| |git commit -m | « titre de modification » Accompagner nos changements d’un message d’explication.| |git push | Cela met à jour le dépôt distant avec vos dernières modifications.|

Il est très important de ne manquer aucune étape et de les effectuer dans l’ordre.

3. Rédiger notre page web#

Nous savons à présent comment utiliser notre terminal ainsi que Git. Maintenant nous allons pouvoir travailler sur notre dossier afin de rédiger notre page web.

3.1 Éditeur de texte#

Afin de pouvoir écrire nos textes sur notre page web, nous travaillerons avec un éditeur de texte. Celui-ci nous permettra de travailler sur notre documentation sans devoir passer par l’espace d’édition présent sur Gitlab. Il existe plusieurs languages comme HTML, utilisé pour créer et structurer des pages web ou encore Markdown qui est un language de balisage légé, utilisé pour formater du texte de manière simple et efficace.

Markdownest l’argement plus pratique pour les tâches que nous voulons faire. L’‘éditeur de texte que j’ai choisi est Visual Studio Code. Celui-ci est pratique car nous pouvons utiliser un format Markdown pour rédiger notre site au lieu de HTML.

Afin de me familiariser avec ce language je me suis entrainé sur ce site. J’ai alors rassemblé les commandes les plus utiles pour notre itulisation :

Commandes	Utilités
#	titre 1
##	titre 2
###	titre 3
**	mettre en gras
_	écrire en italique
[testlien] (lien)	lien online
![testimage] (lien)	image utile
>	paragraphe
*	liste
``	Blocs de code

Voici comment faire un tableau :

| En-tête 1 | En-tête 2 | En-tête 3 | |-------------|-------------|-------------| | Contenu 1 | Contenu 2 | Contenu 3 | | Contenu 4 | Contenu 5 | Contenu 6 |

3.2 Bon à savoir pour Visual Studio Code#

Afin de pouvoir travailler sur Visual Studio code il faut d’abord le télécharger sur ce site. Ensuite j’ai ouvert mon dossier en cliquant sur l’onglet : “ouvir le dossier”, il est important d’ouvrir le fichier dans ton dossier Fablab (nom . nom de famille).

Ensuite j’ai téléchargé Markdown All in One pour pouvoir utiliser le language Markdown sur visual studio code. Pour ce faire, j’ai ouvert l’onglet de recherche en haut à gauche en dessous de l’onglet explorateur.

Une fois installé, je peux utiliser le language Markdown sur Visual studio code. Une fois votre documentation finie, il ne faut pas oublier de mettre à jour le transfert d’information comme expliqué au point 2.3

Je pense qu’il est temps de cloturer ce premier module, en esperant que mes instructions étaient claires. On se revoit pour le module 2 !