Apprendre Markdown : l'outil d'écriture pour les développeurs de logiciels

Si vous êtes ingénieur logiciel, vous avez probablement passé beaucoup de temps à affiner votre environnement pour augmenter votre productivité. Vous avez votre IDE préféré. Vous avez votre débogueur préféré. Vous avez votre outil de surveillance des performances préféré. Mais qu'en est-il de votre outil de rédaction de documentation, de manuels et de rapports ? Après tout, écrire prend un temps non négligeable, n'est-ce pas ? En effet, il est temps de prendre au sérieux votre outil d'écriture.

Et rappelons-nous que vous êtes technique , donc les éditeurs WYSIWYG peuvent ou non être la meilleure option pour vous. Vous ne voulez pas nécessairement (ou même n'aimez pas !) Naviguer dans les menus, les barres d'outils et les rubans pour formater votre texte.

Et si, à la place, vous pouviez facilement ajouter tous vos styles de mise en forme directement dans le texte en tant que syntaxe en ligne simple pour obtenir un texte entièrement formaté ?

Eh bien, en fait, vous pouvez. C'est Markdown et c'est de cela qu'il s'agit dans ce tutoriel.

Quand plus c'est moins…

Les logiciels de traitement de texte sont écrits pour satisfaire un très large éventail d'utilisateurs et de cas d'utilisation et, en tant que tels, doivent fournir toutes sortes de fonctionnalités. Mais clairement, seul un petit sous-ensemble de cette fonctionnalité est susceptible d'être pertinent pour chaque utilisateur individuel. Et pour la plupart des utilisateurs, qui souhaitent simplement créer un document (et n'ont pas besoin de concevoir une brochure ou une affiche marketing), un très petit sous-ensemble des nombreuses options disponibles est pertinent.

En fait, Microsoft s'en est clairement rendu compte il y a quelques années lorsqu'ils ont repensé l'interface utilisateur de Microsoft Word en groupes fonctionnels distincts qu'ils ont appelés «rubans». Pourtant, fait intéressant, la plupart des utilisateurs vous diront qu'ils ont trouvé la nouvelle interface plus déroutante et plus difficile à naviguer que son prédécesseur.

En effet, plus peut parfois être moins lorsqu'il s'agit de facilité d'utilisation et de productivité.

… et quand moins c'est plus

Avouez-le, vous êtes un ingénieur logiciel, pas un graphiste. Vous voulez juste écrire ce manuel, ou document technique, ou rapport, et en finir. Vous serez très heureux et satisfait de certaines fonctionnalités de formatage de base telles que les en-têtes, les listes à puces ou numérotées et les blocs de code. Et, oh oui, une mise en forme de police (gras, italique, etc.) serait également utile. C'est à peu près ça. (Et mec, si vous pouviez même le faire dans vi, ce serait vraiment génial !)

Entrez Markdown.

Qu'est-ce que Markdown ?

John Gruber (avec des contributions substantielles du gourou technique et activiste Internet Aaron Swartz) a créé le langage Markdown en 2004 dans le but de permettre aux gens "d'écrire en utilisant un format de texte brut facile à lire et à écrire, et éventuellement convertissez-le en XHTML (ou HTML) structurellement valide ».

Markdown a été conçu pour être lisible tel quel, sans donner l'impression qu'il a été balisé avec des balises ou des instructions de formatage (contrairement au texte formaté avec un langage de balisage comme RTF ou HTML qui peut être à la fois difficile à créer et difficile à lire dans son format brut ).

Markdown vous permet d'écrire en utilisant un format de texte brut facile à lire et à écrire, qui peut ensuite être converti en HTML structurellement valide. Donc, pour être tout à fait précis, Markdown c'est vraiment deux choses :

1. Une syntaxe de formatage de texte brut
2. Un outil logiciel (dont la première version a été écrite en Perl) qui convertit le formatage du texte brut en HTML.

Markdown intègre une poignée de conventions de syntaxe simples, assez intuitives et faciles à utiliser. Surtout pour vous en tant qu'ingénieur logiciel - qui n'est pas rebuté par le besoin d'apprendre et d'utiliser ces conventions de syntaxe de base - Markdown peut en effet être le chemin de moindre résistance entre ce que vous voulez écrire et le faire écrire.

Apprendre Markdown : Premiers pas

Markdown est facile à apprendre. Super facile. Vous pouvez apprendre les bases en cinq minutes et cela deviendra rapidement une seconde nature. Et - tout comme la relation entre CSS et les préprocesseurs CSS - vous pouvez en utiliser aussi peu ou autant que vous le souhaitez.

Si vous êtes habitué à n'importe quel type de conventions d'écriture de texte brut, vous connaissez peut-être déjà certaines conventions de démarquage, telles que les chiffres ou les tirets au début d'une phrase pour créer une liste, les astérisques autour d'un mot pour l'emphase, etc. au. Ainsi, par exemple, si vous souhaitez afficher quelque chose en italique, entourez-le simplement d'astérisques comme *this* (par opposition à une syntaxe HTML plus maladroite comme <span>this</span> ).

De même, vous pouvez spécifier un titre H1 en ajoutant simplement un préfixe "#" à votre ligne (par exemple, # Section Heading , plutôt que <h1>Section Heading</h1> ).

Une autre grande utilisation de l'apprentissage de Markdown, en particulier pour nous, les ingénieurs en logiciel, est de l'utiliser pour la documentation sur les référentiels de code source. La plupart des dépôts incluent un fichier README.md ( .md est l'extension standard d'un fichier Markdown). Github, par exemple, a son propre « Markdown à saveur Github », qui ajoute des fonctionnalités supplémentaires spécifiquement pour la documentation de développement. Cela peut certainement faire gagner du temps au lieu d'avoir à écrire cette documentation en HTML.

À titre d'exemple simple, supposons que vous souhaitiez inclure l'extrait de code suivant dans votre documentation :

<h2 style=color:#3863a0;font-size:1.5em;font-weight:600;margin-top:2em;margin-bottom:1em;line-height:1.3em;>Initier des plugins</h2>

Lancez pluginName sur votre conteneur en utilisant jQuery comme suit :

$(function() { $('#container').pluginName(); }); En utilisant l'ID de notre conteneur, nous pouvons lancer pluginName avec la méthode jQuery .pluginName() .

Voici une comparaison de la façon dont cela serait fait en HTML par rapport à Markdown :

Pour plus d'aide pour démarrer, il existe de nombreux didacticiels Markdown en ligne pour vous aider à vous mettre à niveau, y compris un aperçu de Markdown par John Gruber (le créateur de Markdown) ainsi qu'un didacticiel Markdown en ligne.

Analyseurs et outils Markdown

Une fois que vous avez écrit votre article dans Markdown, vous aurez besoin d'une application pour analyser la syntaxe en HTML. Il y en a quelques-uns qui sont gratuits , notamment :

• StackEdit - éditeur Markdown basé sur un navigateur qui a quelques options de synchronisation avec des services populaires comme Google Drive et Dropbox
• Online Kramdown Editor - un autre éditeur Markdown basé sur un navigateur avec une interface extrêmement simple
• Mou - le meilleur écrivain Markdown basé sur Mac que j'ai rencontré comme une option plus geek pour les développeurs; des tonnes de fonctionnalités et gratuites (en version bêta) [c'est ce que j'ai utilisé pour écrire cet article]
• MarkdownPad - excellent éditeur Markdown pour Windows
• Textes - un bel éditeur multiplateforme (Mac et Windows) ; exporte vers plusieurs formats tels que PDF, .doc et ePub

Certaines grandes plateformes ont déjà adopté (ou du moins autorisé) l'utilisation du Markdown dans leurs éditeurs pour ceux qui souhaitent l'utiliser. Avec d'autres, tels que WordPress, Evernote et Google Docs, le support natif (au moment de la rédaction de cet article) n'est pas encore intégré, mais des solutions personnalisées ont été introduites par des tiers. Ceux-ci inclus:

• La nouvelle plate-forme de blogs populaire Ghost, dans le but de rationaliser l'écriture en ligne, utilise Markdown pour son éditeur de contenu.
• Pour WordPress, le plugin Jetpack prend désormais officiellement en charge Markdown, que vous pouvez activer sous Paramètres > Discussion si vous utilisez le plugin. Ou vous pouvez utiliser un plugin comme WP-Markdown qui convertira votre contenu de démarquage de publication en HTML, et reviendra à Markdown lorsque vous aurez besoin de le modifier.
• Pour Evernote, certaines applications Markdown telles que l'éditeur en ligne Markable ou l'éditeur Mac Byword permettent l'exportation et la publication directement dans les notes. Ou si vous préférez utiliser directement l'application Web Evernote, vous pouvez utiliser une extension de navigateur appelée Markdown Here qui convertit une note sélectionnée écrite dans Markdown en texte formaté d'un simple clic sur le bouton de la barre d'outils.
• Google Docs ne prend pas encore en charge nativement Markdown, mais quelques éditeurs (tels que StackEdit) exporteront/synchroniseront directement avec Drive.

Les inconvénients

Bien sûr, avec une grande simplicité vient des limites. Comme je l'ai déjà expliqué, Markdown n'a pas été écrit pour des tâches de traitement de texte complexes nécessitant des fonctionnalités de formatage avancées. Si c'est ce dont vous avez besoin, Markdown n'est pas le bon outil.

Mais pour les développeurs qui ont besoin de rédiger un manuel d'utilisation, une documentation technique ou un rapport technique, Markdown offre un équilibre presque parfait entre la simplicité et les fonctionnalités dont vous avez besoin.

Peut-être que le plus gros inconvénient - en particulier pour nous, les ingénieurs qui sommes des accros du contrôle des modifications - est l'incapacité de travailler en collaboration dans Markdown et de suivre les modifications (une exception notable à cela, cependant, est le plugin StackEdit pour Google Docs). Et bien sûr, avec un minimum d'effort, on peut simplement collaborer sur un document Markdown via un référentiel git et ainsi obtenir tout le suivi des modifications et la collaboration dont on a généralement besoin.

Conclusion

Alors, apprendre Markdown est-il pour tout le monde ? Bien sûr que non. Aucun outil ne l'est jamais.

Mais si vous êtes un ingénieur logiciel, cela pourrait très bien être précisément l'outil d'écriture que vous recherchiez. Donc, si vous ne l'avez pas encore essayé, vous devriez vraiment essayer.