Documentation : La quête de la perfection

"Comme du code"

• La documentation est un produit
• Gestion en version avec Git
• Collaboration via les pull requests
• CI/CD: tester et publier automatiquement

Documentation technique

Avec MkDocs +
material theme

Ecrire le texte

Utilisation de Markdown

Avec votre éditeur préféré :

• VSCode
• IntelliJ
• Eclipse

Ecrire le texte (2)

Rajouter des extensions

• markdownlint (pour la syntaxe)
• Draw.io (pour les schémas)
• PlantUML (pour les schémas comme du code)
• Marp (pour les transparents)

Outillage et frameworks

• Jekyll
• Hugo: puissant, léger, rapide
• Marp, sli.dev: transparents / présentations
• MkDocs + material theme

CI: Linter - vérifier le markdown

CLI linter

• github super-linter
• markdownlint
  

Linter dans l'éditeur

• VS Code markdownlint extension

CI: Orthographe

En ligne de commande

• spellcheck-github-actions
• spellchecker-cli

Dans l'éditeur

• VS Code code-spell-checker extension

CI: Vérification liens hypertexte

Liens morts

markdown-link-check

CI: Tester

Style / voix

Vale

Publication (CD)

Formats

HTML | PDF | DOCX | EPUB | MOBI | ...

Hébergement web

• GitHub pages
• GitLab pages
• Netlify
• Un bucket AWS S3