1. Gestion de projet et documentation#

Bienvenue dans ce premier module qui servira avant tout à apprendre comment réaliser une bonne documentation tout en tant se familiarisant avec les outils nécessaires pour y parvenir !

1.1 Pourquoi documenter ?#

Avoir une bonne documentation dans la réalisation d’un projet est très important. En effet cela nous permet de pouvoir toujours revenir sur ses pas. Il est totalement normal de se sentir submergée par toutes les nouvelles informations que ce cours nous apporte. Documenter est donc une manière de libérer toutes ces informations dans un espace sur lequel on peut retourner à tout moment. De plus, pouvoir revoir tout son parcours depuis le jour 1 jusqu’au projet final est assez gratifiant et j’espère pouvoir en inspirer plus d’un.

1.2 Les outils#

De bons outils sont la fondation d’une bonne documentation, et les maîtriser sont essentiels. Pour ceux travaillant comme moi sur un MacBook, voici la liste des outils que j’ai utilisés :

  • Terminal
  • Markdown
  • Homebrew
  • Gitlab
  • Git
  • Visual studio code
  • Mkdocs

Avant de démarrer les différentes procédures pour conceptualiser ma page internet, je me suis d’abord familiarisée avec un premier outil : Terminal. C’est une app présente sur tout les MacBook permettant de communiquer avec le système dʼopération du Mac à lʼaide dʼune interface de commande de ligne(CLI).

Qu’est qu’une CLI ?

Il s’agit d’une interface “utilisateur-ordinateur” où l’utilisateur tape une ligne de commande, c’est-à-dire du texte au clavier pour demander à l’ordinateur d’effectuer une opération. Voici les deux commandes qui m’ont été le plus utiles :

Commande Description
ls liste les fichiers et les sous-dossiers
cd changer de répertoire (suivi du chemin auquel on veut accéder)

1.3 Les procédures#

Lorsque j’ai voulu m’aider des documentation des années précedentes je n’ai jamais trouvé une procédure claire de la démarche à suivre pour créer sa page internet. J’ai donc essayé d’en réaliser une la plus précise possible !

1.3.1 Installer Git#

  • Pour procéder à l’installation de Git il faut d’abord installer un Command line user interface (CLI) afin d’établir une « communication » entre nous et l’ordinateur.
  • Travaillant sur un Mac j’ai pu simplement taper dans l’onglet de recherche « terminal » qui me servira de CLI dans ce cas-ci. Pour télécharger Git j’utilise homebrew : il faut d’abord installer Homebrew en entrant dans un terminal la commande brew install git .
  • Mon mot de passe de Mac m’a é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.

Alt text

1.3.2 Protocole SSH#

Une fois Git installé, il faut à présent créer une connexion sécurisée entre mon ordinateur et le serveur de Gitlab. Le protocole SSH est ce qui va nous permettre d’établir cette connexion par la création d’une paire de clé SSH. Dans cette paire l’une des clé est publique et sera par la suite ajoutée à notre compte Gitlab, l’autre est personnelle et elle 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; sur recommandation, j’ai utilisé « ED25519 » car elle est considérée comme plus sécurisée ainsi que plus performante.

Voici les étapes que j’ai effectuées pour génerer ma paire de clé:

  • J’ouvre mon terminal (équivalent à un CLI)
  • Je tape ssh-keygen -t ed25519 -C  "votre username" dans mon cas : “noa.lipmanowicz”
  • Le message suivant apparaît « Enter file in wich to save the key »
  • J’appuye sur enter
  • A l’affichage de passphrase deux options sont possibles : celui d’introduire un mot de passe, sinon d’appuyer deux fois sur enter si je n’en souhaite pas un
  • Après tout cela, mes clés publique et personnel sont désormais disponibles dans mes fichiers

Que faire si vous ne trouvez pas votre clé?

Pas de panique, le fichier est probablement caché. Face à cette situation, j’ai suivi ce tutoriel qui explique la procédure à effectuer dans ce cas.

  • J’ai copié le code ci-dessous dans mon terminal
  • J’ouvre mon compte Gitlab, je vais dans Mon profil
  • Ensuite dans Préferences
  • Puis dans Clés SSH, et j’appuie sur Ajouter une nouvelle clé
  • J’effectue un command V dans l’espace reservé, et je colle le contenu de la clé. Celle-ci peut être désormais ajoutée !

Alt text

1.3.3 Cloner le projet#

Cette étape consiste à créer une copie de mon projet sur mon ordinateur pour pouvoir travailler directement à partir de celui-ci. Il faut d’abord cloner le projet dans un repository (dossier) dédié au cours, afin de retrouver facilement une copie sur mon ordinateur.

Voici tout d’abord comment réussir à trouver l’URL qui permettra de cloner le projet :

  • Ouvrir Gitlab
  • Allez dans Projet
  • Puis dans Students
  • Ensuite dans Notre compte
  • Appuyez sur Cloner et ensuite Cloner avec SSH

Alt text

Une fois l’URL copié, j’ouvre mon terminal et ouvre le dossier dans lequel je souhaite cloner mon projet. Une fois celui-ci ouvert, j’utilise la commande git clone devant la copie de l’URL pour créer ma copie dans mon repository (ici Phys517). Voici une photo de tout le procédé :

Alt text

Remarque : Pour vérifier que cela a fonctionné, vous pouvez utiliser la commande ls qui vous donnera un aperçu de tous les fichiers présent dans le dossier

Comment copier un dossier dans un terminal MacBook ?
C’est une démarche qui vous servira tout au long des modules. Personnellement je ne savais pas comment faire à l’époque et je n’étais pas la seule. Je vous ai donc mis ci-dessous la démarche à effectuer ;) :

Alt text

Après avoir Copier “Bureau” en tant que nom de chemin, vous Collez ceci dans votre terminal en rajoutant la commande cd devant pour vous retrouver à l’intérieur de votre dossier!

1.3.4 Synchroniser la copie sur mon ordinateur avec le serveur Gitlab#

Grâce à la connexion sécurisée que je viens de créer, à l’aide de plusieurs commandes, je peux synchroniser tous les changements que je vais effectuer à partir de mon ordinateur (via Visual Studio Code) sur le serveur Gitlab.

Commande Description
git pull Télecharger la dernière version du projet
git add -A Ajouter tous les changements
git commit -m “titre de modif” Accompagner nos changements d’un message d’explication
git push Envoyer nos changements sur le serveur

Il faudra utiliser ces différentes commandes dans la CLI (interface de commande de ligne) que vous utilisez. Pour ma part, je vais me servir de l’application Terminal. Voici la procédure détaillée de la synchronisation avec les différentes commandes :

Alt text

1.3.5 Rediger sa page web#

1. Editeur de texte#

Notre documentation aura comme forme finale une page web que nous allons pouvoir modifier à l’aide d’un éditeur de texte. 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 qui est plus dur à comprendre.

A l’aide de ces deux sites internets R Markdown Cheat Sheet et Markdown Cheat Sheet j’ai pu réunir les commandes nécessaires à connaître pour bien utliser Markdown :

Commande Description
#Titre Titre
## Sous-titre Sous-titre
mot en **gras** mot en gras
mot en italique mot en italique
1. premier élement \n 2. deuxième élement Alt text
- premier élement \n - deuxième élement Alt text
Image : ![image](image.jpg) image
Lien : [nom du lien](adresse) nom du lien
Alt text code
2. Importer et éditer des images#

Afin d’illustrer au maximum ma page web, j’ai dû apprendre à importer et éditer des images. Pour commencer, il faut décider quel format nous allons utiliser, JPEG ou PNG.

Quelle est la différence ?

  • Le format JPEG va s’appuyer sur une méthode de compression qui réduit la taille des fichiers et permet une certaine optimisation de l’espace de stockage. Mais bien que ce format soit plus léger, il utilise une méthode de compression avec perte qui supprime des données de l’image. Au fur à mesure du temps, cette compression avec perte peut rendre les fichiers de moins bonne qualité.

  • Le format PNG est une compression sans perte, ce qui permet qu’aucune données ne soit perdue lorsque l’image est compressée, ainsi l’image reste intacte. Ce format va également prendre en charge plusieurs millions de couleurs et les arrière-plans transparents, idéal pour jouer avec les couleurs.

Importer#

J’ai décidé d’utiliser un format JPEG pour mes photos. Je vais directement les importer à partir de mon éditeur de texte, Visual Studio Code. Il suffit de convertir la photo que je souhaite utiliser en format JPEG à l’aide d’un convertisseur en ligne, j’ai beaucoup utilisé celui-ci.

Une fois ma photo convertie :

  • j’ouvre le dossier où se trouve la copie de mon projet
  • je vais dans mon dossier Image
  • je copie ma photo dedans
  • j’ouvre Visual Studio Code
  • je retrouve mon image, je fais un clique droit, et je colle l’image où je le souhaite

Alt text

Editer#

J’ai plusieurs alternatives pour éditer mes images. La première option est d’ouvrir les paramètres de la photo importée sur mon ordinateur afin de modifier sa taille, la recadrer, la retourner,…

Alt text

Comme seconde option, je peux utiliser un programme manipulation et de retouche d’image comme Gimp qui permet :

  • de changer la compression du format (outil très utile qui permet d’alléger la perte de qualité lorsque que l’on convertit notre image en JPEG)
  • de modifier la taille
  • de recadrer
  • de retourner
  • d’effectuer une correction des couleurs

Remarque : on édite nos images pour essayer d’optimiser l’espace de stockage au maximum ! Le défi va être de les rendre les plus “légéres” possible tout en gardant une bonne qualité.

3. Importer une vidéo#

On peut également importer des vidéos pour illustrer notre documentation. Ces vidéos peuvent être par exemple :

  • un enregistrement d’écran
  • une vidéo en format : GIF, mp4 (meilleur format pour insérer les vidéos sur notre site), mov, avi
  • une vidéo youtube

Comment importer une vidéo ?

Il y a différentes procédures en fonction du type de vidéo que vous voulez importer. Pour ma part je vais la plupart du temps utiliser des vidéos enregistrées sur mon ordinateur. Je vais d’abord toutes les convertir en format mp4 car cela m’a été fortement recommandé.

Ensuite, j’ai suivi ces instructions pour écrire en HTML les lignes de commandes me permettant d’importer ma vidéo :

<video controls>
            <source src="video mouvement.mp4" type="video/mp4">
</video>
  • la commande controls permet de contrôler la vidéo : mettre en marche, mettre pause, et modifier le son.
  • la commande source permet de spécifier quel fichier vidéo on utilise.

Si l’on veut modifier la taille du fichier on peut le faire avec l’aide des commandes width et height

<video width="320" height="240" controls>
    <source src="video mouvement.mp4" type="video/mp4">
</video>
4. Avoir un aperçu de notre site#

Pour ne pas de voir attendre à chaque fois que notre site internet soit mis à jour (entre les nuits de mardi et mercredi et entre celles de mercredi et jeudi) pour obtenir un aperçu, il existe une alternative : MkDocs

MkDocs est un outil qui permet de générer un site web à partir de fichiers Markdown. Pour pouvoir l’utiliser, il faut d’abord trouver le fichier de configuration écrit en YAML.

Si vous ouvrez le dossier docs, qui comprend tous nos fichiers de documentation, vous y trouverez un fichier du nom de mkdocs.yml. C’est notre fichier de configuration ! Pour pouvoir personnaliser les informations dans le fichier mkdocs.yml., j’ai mis à jour site_name, site_author, site_url, repo_url et j’ai choisi mkdocs comme thème.

Pour finir si nous voulons avoir un aperçu direct de nos fichiers Markdown, sans devoir attendre la mise à jour chaque mardi et jeudi de notre site internet, Mkdocs le permet. Il suffit grâce à ces instructions d’installer Mkdocs sur son ordinateur et par la suite de se servir de la commande mkdocs serve sur le Terminal de Visual Studio Code pour avoir à tout moment un aperçu de notre site internet.

Alt text

1.3.6 Gestion de projet#

Différentes techniques de gestion de projet nous ont été proposé par notre professeur Denis. Cet article m’a permis de rassembler les différentes techniques que j’essayerais de garder en tête et de mettre en pratique dans ce cours :

  • Décomposition des tâches :

L’une des premières questions que Denis nous a posé et que mon père m’a également beaucoup de fois demandé : “Comment mange-t-on un élephant?”. La réponse est simple, il faut le morceaux par morceaux, petit à petit. C’est la même chose pour un projet. Décomposer les tâches est une manière de visualiser les différents morceaux par lesquels on devra passer avant la finalité du projet. De cette manière nous aurons l’impression de faire un pas de plus après chaque tâche realisé.

  • Gestion en spirales :

Afin d’arriver le plus rapidement possible à un prototype final, il va falloir d’abord échouer. En effet, Denis nous a directement dis la phrase : “Fail fast” qui veut dire échouer rapidement. Il ne faut pas prendre cette phrase comme décourageante, au contraire, ce que Denis veut dire c’est que personne n’arrive du premier coup à son projet final. Il va falloir passer par différents prototypes, modèles qui permettront de tester les paramètres qui nous intéressent. Le conseil est donc de réaliser rapidement une première version minimale fonctionnelle du projet, puis évoluer en ajoutant des fonctionnalités ou des améliorations en spirales successives. De cette manière, notre prototype final sera le plus proche de celui souhaité.

  • Gestion du temps :

Le temps est sûrement l’ennemi numéro 1 dans la réalisation d’un projet. En effet, comme on le sait tout prend toujours plus de temps que prévu et c’est une chose à prendre en compte. Lors de la décompostion des tâches, il est impératif d’y ajouter également un délai. C’est une manière d’éviter la panique et surtout d’avoir une ligne du temps précise de l’avancement de notre projet.

1.3.7 Checklist du module#

  • made a website and describe how you did it ✔️
  • introduced yourself ✔️
  • documented steps for uploading files to the archive ✔️
  • documented steps for compressing images and keeping storage space low ✔️
  • documented how you are going to use project management principles ✔️
  • pushed to the class archive ✔️