# Gestion de la documentation (Markdown)

[Source](https://www.simplilearn.com/project-documentation-article)

## Pourquoi documenter ?
Il est possible d'oublier ce qu'on a codé après plusieurs jours (ou plusieurs heures, on ne juge pas votre mémoire )) . **La documentation** est alors très importante puisque celle-ci vous permet de vous souvenir de ce que vous avez fait !

**Attention à ne pas mettre trop de détails inutiles...**

De plus, si vous faites un travail d'équipe, ce n'est pas tout le monde qui s'y retrouve dans votre manière de penser! Une bonne documentation va permettre à vos cooéquipers de mieux comprendre ce que vous voulez faire.

************
## Bonnes pratiques à exercer dès maintenant

* Rédiger des **titres courts** et **descriptifs**
* Éviter les **captures d'écran** (Elles ne seront peut-être pas toujours à jour!)
* Écrire **au présent** (Le lecteur va être moins confus si vous dites "Le logiciel peut [...]" que "Le logiciel pourrait [...]")
* Organiser la documentation de façon logique, **les listes et les titres** sont très utiles à cet effet!
* **Diviser** les **pages** par sujet
* Favoriser **les exemples** aux descriptions
*
************
## Comment utiliser la syntaxe markdown ?

La syntaxe markdown permet de modifier le style de votre écriture pour améliorer la lisibilité et la division du texte ou de votre documentation.

Pour les titres, on utilise **le caractère '#'**.

### Titres

#### Différentes versions pour les titres:

* # H1 *#*
* ## H2 *##*
* ### H3 *###*
* #### H4 *###*
* ##### H5 *#####*
* ###### H6 *######*

### Démarquation du texte

Le markdown permet de d'accentuer votre texte et de donner de l'attitude :sunglasses: à votre documentation.

#### Différentes façons d'accentuer votre texte

Pour écrire en _italique_ il suffit d'ajouter le caractère '*' ou '_' avant et après la portion du texte que vous voulez modifier

Pour écrire en **GRAS** il suffit d'ajouter le caractère '**' ou '__' avant et après la portion du texte que vous voulez modifier

Pour combiner les deux , il suffit de combiner le **gras** et l'**_italique_** pour donner un ***italique gras***.

Pour rayer votre texte en le caractère '~~' avant et après la portion du texte que vous voulez modifier ~~Texte rayer~~

### Pour diviser votre texte

Il est important d'utiliser les listes pour diviser vos idées et vos points importants

##### Façon de créer une liste
La **liste à point ordonné** est une liste utilisé dans un contexte où il y a des **étapes à suivre** avec un **ordre bien précis**. On la **déclare** avec un '*numéro de l'étape* + .' en début de ligne ex: 1.
1. Premier élément
2. Deuxième élément
3. Troisième élément
4. Quatrième élément

* La liste à point non ordonné est déclarée en utilise un '*' simple en début de ligne

Liste et sous points
1. premier
⋅⋅1. sous-élément
4. un autre élément

### Inclure des éléments à l'intérieur de votre documentation

#### Images, Liens et Vidéos Youtube

##### Liens -> [On écrit le lien entre crochet et on place notre liens dans les parenthèses](https://www.google.com) [texte] (lien)

##### Images et Vidéos youtube->
on fait la même chose pour les images et les vidéos youtubes

### Cosntruction des tableaux

Voici un exemple :

On utilise les '|' pour diviser les colonnes

| Tableaux | sont | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |

### Séparation horizontale

Il y a plusieurs variantes pour les séparations horizontales,
mais elles font toutes le même travail

Trois ou plus de chaque caractère '---' ou ' ***' ou ___...

---

Exemple 1 ("*"):

***

Exemple 2 ("-"):

___

Exemple 3 ("_"):
___

:cool: Vous êtes maitenant des pros de la syntaxe markdown :cool:

***
[Source](https://www.lockheedmartin.com/en-us/suppliers/documentation.html)
[Info Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
***