Documentation

Les documents en tant que code ne sont pas forcément synonymes de Markdown et de Git

Après presque 15 ans en tant que rédacteur technique pour des sociétés de logiciels, je suis un converti à la philosophie de la documentation en tant que code. Mais si j’aime Markdown et Git (je les utilise pour ce site web), je ne les utiliserais pas pour documenter des logiciels d’entreprise. Je ne bénéficierais pas des avantages des outils de documentation dédiés, tels que la création structurée, la source unique et les PDF de haute qualité, pour n’en citer que quelques-uns. On vous a peut-être dit que vous deviez abandonner vos outils et devenir plus proche d’un développeur pour faire de la documentation en tant que code, mais je ne pense pas que ce soit vrai.

Écrire américain quand ce n'est pas son premier dialecte anglais

Lorsque j’ai commencé à écrire, j’utilisais l’anglais d’Oxford. C’est celui qui contient les orthographes -ize (correctes). Bien qu’en tant que journaliste, on m’ait dit d’éviter la ponctuation inutile, j’évite donc la virgule d’Oxford (sérielle). Mais lorsque je suis devenu rédacteur technique, je me suis retrouvé à utiliser l’anglais américain dans mon travail quotidien. Finalement, j’en ai eu assez de passer d’une langue à l’autre et j’ai décidé d’utiliser exclusivement l’anglais américain. Dans cet article, j’utiliserai le terme “colonial” pour désigner tous les dialectes non américains de l’anglais.

Migrer du Markdown à la rédaction structurée

Je suis un grand fan de Markdown. Il est parfait pour les wikis et la rédaction de contenu pour les sites statiques (la plupart du contenu de ce site est rédigé à l’aide de ce langage). Mais il arrive un moment dans la documentation d’un logiciel où la taille du projet ou le nombre de contributeurs a augmenté au point qu’il est nécessaire d’imposer une certaine structure. C’est à cela que servent les documents structurés. L’une des principales raisons pour lesquelles vous souhaitez le faire est de séparer le contenu de la présentation. Cela vous permet de présenter le contenu de différentes manières sur différents supports, tels que l’imprimé et l’Internet. Mais vous avez déjà tout ce contenu en Markdown. Quelles sont donc les options qui s’offrent à vous: Vous pouvez tout recréer à partir de zéro (ne le faites pas). Ou vous pouvez migrer de Markdown vers un système de rédaction structuré.

Créer une documentation en XML

Si votre documentation a atteint les limites de ce qui est possible en Markdown, et que vous préférez ne pas revenir au HTML, il est temps d’envisager la rédaction en XML. Et non, je ne parle pas d’utiliser Microsoft Word et d’enregistrer au format .DOCX. Quel que soit le schéma que vous choisissez (DITA, DocBook, XHTML ou autre), vous bénéficierez des avantages du single sourcing et du structured authoring, ce qui vous fera gagner du temps et de l’argent, surtout si votre documentation est traduite dans d’autres langues.

Créer de la documentation dans un environnement agile

Cherchez sur Google des images de agilité, et vous obtiendrez des concours de chiens. Poursuivons donc cette analogie. Si vous créez du contenu écrit pour des logiciels, le passage de l’approche en cascade à l’approche agile peut vous donner l’impression d’être un chien confronté à l’improviste à une course d’obstacles à l’heure des promenades. Et au lieu d’une fois par jour, les promenades ont lieu toutes les heures. Ce n’est peut-être pas la meilleure analogie. Je ne sais pas quel est l’équivalent pour un chien de devoir jeter tout le travail que vous avez fait la semaine dernière et de recommencer à zéro. D’accord, recommençons.

Démarrer avec les API REST

Les API (interfaces de programmation d’applications) REST (representational state transfer) existent depuis le début du siècle, lorsqu’elles ont été définies par Roy Fielding dans sa thèse de doctorat. Depuis, elles sont devenues la principale méthode de connexion des composants dans les architectures microservices.

Revisiter DocBook

La Darwin Information Typing Architecture (DITA) et DocBook sont deux cadres de rédaction basés sur XML. Je préfère de loin DocBook. L’article d’aujourd’hui est une mise à jour d’un article sur le sujet que j’ai initialement écrit pour le numéro du printemps 2011 de Communicator. J’avais peut-être raison, car en 2014, un groupe de spécialistes de la DITA a abandonné la consultation pour créer son propre système de gestion de contenu (CCMS) basé sur DocBook.

Créer un guide de rédaction (pour l'anglais)

Lorsque je suis passé du journalisme à la rédaction technique, les deux choses qui m’ont le plus manqué sont les guides de style et les rédacteurs. Lorsque les services de rédaction technique sont réduits, les rédacteurs sont les premiers à être licenciés. À trois reprises, quand j’étais le seul rédacteur d’une organisation, j’ai créé mon adéquat guide de style à partir de rien. Mais même quand il existe un guide de style, il peut ne pas être à jour en ce qui concerne la terminologie moderne ou l’utilisation du langage. Si votre travail consiste à rédiger des contenus destinés aux clients, surtout si vous n’avez pas suivi de formation de rédacteur, vous avez besoin d’un guide de style.

Création d'une documentation sur les API pour les projets en langage assembleur

Cette semaine, je publie ce que j’espère être l’avant-dernière bêta de SE Basic IV (un interpréteur BASIC classique open source). La dernière bêta devrait contenir les fonctionnalités sonores et graphiques manquantes, avant de passer à la version candidate.