Markdown vs LaTeX : quel outil utilisez-vous pour écrire la documentation de vos projets ?

Markdown serait plus performant mais ne peut pas transporter des données

Markdown vs LaTeX : quel outil utilisez-vous pour écrire la documentation de vos projets ?
Markdown serait plus performant mais ne peut pas transporter des données

Quel outil utilisez-vous pour écrire la documentation de vos projets ? Vous avez forcément une préférence pour un outil donné, mais y en a-t-il un qui est plus performant que les autres ? Dans le lot d’outils qui existent, l’on retrouve Markdown et Latex. Pour les certains, Markdown est l’outil le plus performant pour écrire son document, mais pour d’autres, il présente des incohérences et ne peut pas transporter des données. Pour ces derniers, il faut choisir Latex à la place afin de fournir un travail correct. Voici certaines choses qu’ils disent dans leur argumentation.

Markdown est un langage de balisage léger créé en 2004 par John Gruber avec l'aide d'Aaron Swartz. L’objectif est de mettre à disposition un langage doté d’une syntaxe facile à lire et à écrire. Un document balisé par Markdown peut être lu en l'état sans donner l’impression d'avoir été balisé ou formaté par des instructions particulières. De l’autre côté, LaTeX est un langage, mais aussi un système de composition de documents. C’est une collection de macro-commandes qui cherchent à faciliter et à améliorer l'utilisation du « processeur de texte » TeX de Donald Knuth.

Pour Jeff Geerling, développeur Web et logiciel, Markdown est un excellent choix pour écrire son document. Selon lui, Markdown suffit dans 98 % pour mettre en place une documentation en bonne et due forme, ce qui lui donne un avantage considérable sur les alternatives qui existent. Il soutient que Markdown est essentiellement du texte simple que tout le monde peut apprendre à écrire en quelques secondes seulement, avec des fonctionnalités supplémentaires. De même, il cite aussi comme argument le fait qu’il existe une multitude de bibliothèques pour l’outil.


« Le fait que le plus petit dénominateur commun de Markdown soit “je peux écrire du texte simple”, associé au fait qu'il existe de très bonnes bibliothèques pour Markdown dans tous les langages imaginables, signifie qu’il est le moyen le plus simple dont vous disposez pour pouvoir écrire une documentation maintenable, quel que soit l'auteur qui contribue à votre base de code », a-t-il écrit. Selon lui, il est plus facile de modifier une documentation en texte clair qu’une autre écrite dans un format spécifique, moins populaire et nécessitant plus de spécificité.

Cependant, selon HIllel Wayne, un programmeur et conseillé en méthodes formelles, Markdown n’est pas du tout l’outil idéal pour écrire une bonne documentation. Selon lui, Markdown est tolérable pour écrire les documents courts, comme un readme.md. « En dehors de ça, ce n'est pas le bon outil pour le travail », a-t-il écrit. Markdown est juste une question de formatage, pas d'information, selon lui. Autrement dit, c’est juste une façon d’écrire du HTML plus simple et plus beau. Les gens l’utilisent parce qu’il est facile à apprendre.

En outre, il estime que les gens le choisissent parce qu’il est facile d'écrire une sorte d'analyseur Markdown dans n'importe quel langage de programmation. Pour lui, Markdown ne peut pas transporter des données. Il n’existe aucun moyen d'intégrer des propriétés dans un texte en utilisant Markdown. Il estime qu’une bonne documentation n’est pas une question de formatage, mais elle concerne le balisage sémantique. De plus, il n’est pas extensible. En effet, il estime que quand vous utilisez Markdown, vous n’avez droit qu’à trois types de formatage : gras, italique et code.


Si c’est le cas, que faire si vous souhaitez que certains éléments de la documentation soient colorés en bleu ? Ce type d’action n’est pas faisable. Vous ne pouvez que changer le CSS pour <em>, mais vous perdez l'italique dès lors que vous faites cela. Toutefois, il rappelle que Markdown peut être extensié uniquement en ajoutant du HTML brut. Le HTML est interprété comme du HTML à l'intérieur d'un document Markdown. Mais l’objectif de Markdown est d'éviter d'avoir à écrire du HTML en premier lieu. Vous ne pouvez pas non plus “hybrider” le Markdown avec du HTML.

En fait, ce qui se trouve dans les balises HTML ne sera pas analysé comme Markdown. Les gens ont essayé de résoudre ce problème avec les extensions pour l’outil, mais elles sont directement ajoutées au moteur de Markdown, et non dans le cadre d'une fonctionnalité d'extensibilité de ce dernier. Si vous voulez avoir une nouvelle chose, vous devez modifier le code du moteur. Par exemple, c’est ce qui arrive avec des images avec une légende. Ceci ne fait pas partie des spécifications de Markdown. En outre, il estime que Markdown ne propose qu’un traitement local.

Enfin, le dernier argument qu’il trouve en défaveur de Markdown est qu’il est juste bon pour écrire du HTML, mais pas du tout adapté pour écrire des documents PDF par exemple. Selon lui, une documentation doit être consultable hors ligne. Ainsi, si vous ne fournissez pas un PDF pour cela, il faut que vous proposiez au moins un lien pour télécharger les documents. Comme alternative, il vous propose d’utiliser reStructuredText ou RST pour écrire vos documentations. Selon lui, Latex est un bon outil, mais il n’est pas meilleur que Markdown.

D’après lui, avec reStructuredText, vous pouvez ajouter toutes sortes d'autres choses, comme montrer ou cacher des sections ou intégrer des mathématiques. Cela dit, l'inconvénient est qu'il est plus complexe que Markdown. Une autre alternative qu’il propose est AsciiDoc. Selon lui, AsciiDoc semble être très utile aussi.

Pour finir, selon Jeff Geerling qui soutient que Markdown est le meilleur outil pour vos documentations, il y a souvent de bonnes raisons de préférer une option plus structurée, comme reStructuredText, LaTeX ou Asciidoc. Cela arrive surtout dans le cadre des projets où un texte plus formel est nécessaire, ou lorsque vous devez prendre en charge la mise en forme de textes spécialisés et structurés. Néanmoins, Jeff Geerling pense que Markdown est le meilleur et le plus flexible des outils pour une documentation.

Sources : Jeff Geerling, HIllel Wayne

Et vous ?

Quel est votre avis sur le sujet ?
Quel outil utilisez-vous pour écrire la documentation de vos projets ?
Quelle est votre préférence, Markdown ou LaTeX ou autres ? Pourquoi ?

Voir aussi

Mark Text : un éditeur Markdown simple et élégant axé sur la rapidité et la convivialité selon son développeur. Disponible pour macOS, Windows et Linux

YouTrack 2019.3 est disponible avec un support HTML dans Markdown et d'autres nouvelles fonctionnalités et améliorations

Utilisez Markdown pour rédiger des articles ou tutoriels sur Developpez.com, en plus des autres outils toujours disponibles