Markdown
Documentation écrite par un programmeur
La documentation est généralement l'un des aspects les plus négligés d'un projet de développement logiciel. En effet, les programmeurs préfèrent souvent écrire du code plutôt que de la documentation. Toutefois, la documentation est essentielle à la compréhension d'un projet par d'autres programmeurs. On veut entre autres savoir comment installer le projet, comment le configurer et comment l'utiliser.
Dans le but de rendre la documentation plus facile à écrire, les programmeurs ont créé un langage d'écriture de fichier de texte riche nommé Markdown. Le Markdown nous permet d'écrire du texte simple qui sera traduit dans un fichier à l'affichage complexe similaire à un document Microsoft Word ou Google Docs. Le tout, sans quitter notre éditeur de code. C'est un langage simple à apprendre et très utile pour écrire de la documentation rapidement.
Il est primordial de bien documenter un projet avec le Markdown. Ils sont un très bon complément aux commentaires dans le code source pour expliquer le fonctionnement du code. Ils permettent aussi de documenter les procédures, les décisions de conception et les choix technologiques du projet.
Créer un fichier Markdown
Pour créer un fichier Markdown, il suffit de créer un fichier texte avec l'extension .md. Vous pouvez le créer directement dans votre éditeur de code préféré. Par la suite, vous n'avez qu'à écrire du texte et à utiliser les balises Markdown pour formater votre texte. Voici quelques exemples de balises Markdown:
- # Titre pour créer un titre
- **Gras** pour mettre du texte en gras
- *Italique* pour mettre du texte en italique
- [Lien](https://example.com) pour créer un lien vers un autre fichier (markdown ou autre)
-  pour afficher une image
Pour voir la liste complète des balises Markdown, vous pouvez consulter le site web suivant:
- Markdown Guide pour la syntaxe de base.
- Markdown Guide pour la syntaxe étendue.
- Basic writing and formatting syntax pour avoir une idée des options spécifiques à GitHub.
Intégration avec les serveurs Git
Les serveurs Git offrent souvent une intégration avec le Markdown pour faciliter la création de documentation pour un projet. Par exemple, GitHub permet d'afficher les fichiers Markdown directement dans le navigateur pour que tout le monde puisse les lire. Cela permet de rendre la documentation accessible à tous les membres de l'équipe.
Vous trouverez souvent un fichier README.md à la racine d'un projet sur GitHub. Ce fichier contient généralement une description du projet ainsi que des instructions pour l'installation et l'utilisation du projet. De nombreux projets utiliseront aussi un dossier /docs dans lequel on regroupe la documentation du projet. La majorité des fichiers Markdown sont écrits dans ce dossier.
Utilisation personnelle
Le Markdown n'est pas seulement utile pour la documentation de projet. Il peut aussi être utilisé pour prendre des notes, écrire des articles de blogue, envoyer des messages dans certains services de messagerie, etc. C'est un langage simple et rapide à écrire qui permet de formater du texte rapidement. Je vous recommande fortement de l'utiliser, entres autres, pour écrire vos notes de cours.
Des logiciels comme Obsidian peuvent être très utile pour gérer vos notes Markdown. Ils offrent des fonctionnalités avancées pour organiser vos notes, les lier entre elles et les rechercher rapidement. Je vous recommande fortement de les explorer!