En tant que développeurs et développeuses, notre environnement de développement est notre outil principal.
Vous avez sans doute, comme moi, rencontrez des difficultés dans la manipulation de documents de type bureautique.
Ajouter des extraits de code, récupérer une commande formatée, sont de tristes expériences qui vont vous attirer vers la doc as code.

Le premier principe qui va nous intéresser est de pouvoir nous concentrer sur le fond des documents à produire, et non sur leur forme.
Évidemment cette dernière reste importante, et nous allons y revenir.
Mais, rester focalisé sur le contenu, en apportant des indicateurs simples, est réellement confortable. Un confort qui s'illustre rapidement dans la mise en évidence de certaines idées, ou l'emphase de portions de texte particulières comme du code.

En complément, si vous êtes habitués des outils du web, que ce soit des forums, des encyclopédies (type Wikipédia¹), vous pratiquez déjà probablement ce type d’écriture à balisage faible. Il en existe d’autres, mais nous ne citerons ici que Markdown², ou Asciidoc³ qui sont utilisés dans de nombreux projets informatiques.

De mon côté, je suis tombé dans Asciidoc³. Sans considérer que cette syntaxe soit meilleure, j’y trouve une plus grande cohérence et un balisage faible permettant de conserver la lisibilité du texte brut⁴. Les outils qui vont suivre sont issus de cet écosystème, même si des équivalents existent.

Vous pourrez jauger de ces différences entre Markdown² et Asciidoc³ dans cette version, de l'article au le format Asciidoc³.

Écrire : n'est-ce pas la base ?

Derrière nos outils parfois complexes, je vous invite à vous concentrer sur l'essentiel : écrire.
Et croyez-moi, faire simple, est parfois compliqué !

Malgré la nécessité d'écrire, le balisage léger de Asciidoc³ va apporter immédiatement de la structuration.
Il vous sera alors possible, tout en restant focalisé sur ce que vous écrivez, d'organiser toutes vos idées par chapitres, par listes, ou éventuellement par tableaux.
Des = pour les niveaux de titre, quelques * ou . pour gérer vos listes, et le tour est joué.

Et tout comme votre code, vous pourrez découper vos productions en différents fichiers. Il sera ensuite aisé d'inclure tout ou partie de ces notes, toujours grâce aux syntaxes d'Asciidoc³, même si cette fois, elles sont moins légères.

Consultez la documentation Asciidoc³ pour connaître les différentes possibilités de cette syntaxe.

Sachez qu'il existe dans tous nos IDE des plugins pour permettre un rendu au fil de l'eau de ce que vous écrivez.
Ce sera là votre premier outil et voici à quoi cela peut ressembler :

Remarquez ici l'inclusion d'une image.
Il peut s'agir d'une des premières difficultés.

Si vous avez besoin d'insérer des illustrations, vous devrez les gérer en externe et les inclure à vos écrits.
La manipulation de ces images, en positionnement, en taille, ou pour les amender ne sera pas possible facilement dans l'outil de doc as code

Ces syntaxes n'évitent pas des travers habituels de notre métier.
Rapidement, nous arrivons à produire des systèmes complexes difficiles à prendre en main.
Il sera alors indispensable de se recentrer sur les basiques : écrire, organiser ses idées, rendre une mise en page simple, mais fluide.

En un mot, comme dans notre code applicatif : Keep It Simple Stupid, KISS⁵ pour les intimes !

Partager vos documents : comment aller à l'essentiel ?

Ecrire, c'est bien, mais partager c'est encore mieux !
À ce stade, je vous ai montré comment produire des documents simples et visualiser le rendu en direct. Découvrons ensemble quelques astuces pour collaborer et partager simplement vos réalisations

L'outil collaboratif par excellence du monde du développement est sans aucun doute Git.
Accompagné de ses gestionnaires de dépôt (Gitlab, Github, etc.), vous pourrez mettre en place des processus de relecture et de validation bien connus de vos équipes.

Si toutefois ces pratiques ne vous sont pas familières, utilisez ces outils localement.
Il vous faudra alors générer localement les documents pour pouvoir les partager.

Côté génération, un premier outil intéressant et dont tout le monde dispose, est votre navigateur.
Ce dernier met à disposition des plugins qui vont vous permettre un premier rendu de vos écrits.
Utilisez ensuite la fonction imprimer de votre navigateur, et hop, vous avez un format PDF partageable.

Pour des générations plus automatisées ou systématisées, il faudra mettre en place une chaine de publication.

Vous rencontrerez alors votre seconde difficulté : la mise en place de ce type de chaine.
C'est naturel lorsque vous généralisez ces pratiques sur une équipe ou plus !

Si toutefois vous préférez un format orienté web, il existe des outils de conversion en HTML.
Dans l'écosystème Asciidoc³, on peut citer Asciidoctor⁶, ou encore Antora⁷:.

L'usage de ces produits nécessite l'utilisation de processus plus ou moins automatisé et d'une gestion des sources avancée.

Coté design, ils sont souvent assez épurés. Ils permettent cependant une mise en forme simple et efficace.

Vous constatez que suivre notre mantra KISS⁵ est plus difficile lorsqu'on parle de partage et de publication.

Se limiter à son navigateur est possible.
Mais si vous tombez amoureux de ces outils vous devrez rapidement passer à la vitesse supérieure.

Alors, quand est-ce que vous vous y mettez ?

La simplicité est indispensable lorsque l'on débute en doc as code.

La fluidité de l'écriture au kilomètre et la structuration de vos idées au fil de l'eau sont l'atout essentiel de ces pratiques.
Par expérience, ils nous apportent un confort mental incroyable au moment de la rédaction en déversant le flots des idées dans des fichiers simples à relire.

Mais l'appropriation des outils de doc as code n'est pas toujours un long fleuve tranquille...
Vous y lancer changera forcément votre approche des supports écrits, mais n'oubliez pas d'emprunter ce chemin étape par étape.
Cela peut être, par exemple, en commençant par la prise de notes, puis la rédaction de document, pour aller jusqu'aux illustrations...

Vous risquez cependant d'avoir besoin dès vos premières publications de personnaliser vos rendus.
Charte à suivre ou simple envie d'esthétisme, vous aurez besoin de compétences et de temps.

Mais ceci est une autre histoire...

1. https://fr.wikipedia.org/wiki/Wikip%C3%A9dia ↩

2. https://www.markdownguide.org/ ↩

3. https://asciidoc.org/ ↩

4. https://arcanneero.gitlab.io/publications/current/doc-as-code/docs-as-code-01-start.html ↩

5. https://fr.wikipedia.org/wiki/Principe_KISS ↩

6. https://asciidoctor.org/docs/ ↩

7. https://docs.antora.org/antora/latest/ ↩