Documentation as code: contrôler la qualité !

AmigaOS

"Document as code" consiste à utiliser toutes les bonnes pratiques que nous utilisons pour notre source code et de les appliquer à la documentation. Les points clés sont :

• Utiliser un outil de gestion des sources (git) et de préférence le même que pour les sources.
• Un format de texte simple (pas de XML) comme AsciiDoc.
• Faciliter la barrière à l’entrée en proposant un lien pour éditer la documentation sur chaque page et pour soumettre une pull request.

Lorsque cette bonne pratique est en place, se pose une seconde catégorie de problème. Comment garantir la qualité :

• Test systématique des exemples de code
• Respect des conventions de documentation
• Métriques et dashboard pour garantir la qualité
• Partage de bonnes pratiques/revue de documentation.

Ce quickie est un rapide retour d’expérience qui présente cette bonne pratique de documentation et qui donne un aperçu de ce qui peut être mis en place pour s’assurer de la qualité de la doc.