Documentation as Code

La Documentation as Code (Docs as Code) est une méthodologie qui traite la documentation comme du code source, en utilisant les mêmes outils de versionnement, workflows de révision et pipelines CI/CD. Cette approche permet aux équipes techniques de maintenir leur documentation directement aux côtés du code, garantissant synchronisation et qualité grâce aux pratiques éprouvées du développement logiciel.

Fondements de la Documentation as Code

• Stockage de la documentation dans des systèmes de contrôle de version (Git) aux côtés du code source
• Utilisation de formats texte légers et portables comme Markdown, AsciiDoc ou reStructuredText
• Application des workflows de développement (branches, pull requests, revues de code) à la documentation
• Automatisation de la génération, validation et déploiement via des pipelines CI/CD

Avantages stratégiques

• Synchronisation automatique entre code et documentation grâce au versionnement commun
• Collaboration facilitée avec workflows de révision et validation identiques au code
• Traçabilité complète des modifications via l'historique Git et les commits liés
• Réduction drastique de la documentation obsolète par proximité avec le code modifié
• Déploiement automatisé et publication continue à chaque fusion sur la branche principale
• Accessibilité améliorée pour les développeurs utilisant leurs outils quotidiens

Exemple concret d'implémentation

name: Documentation Pipeline

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'src/**/*.md'
  pull_request:
    paths:
      - 'docs/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Validate Markdown
        uses: DavidAnson/markdownlint-cli2-action@v11
        with:
          globs: 'docs/**/*.md'
      
      - name: Check links
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          folder-path: 'docs'
      
      - name: Spell check
        uses: streetsidesoftware/cspell-action@v2
        with:
          files: 'docs/**/*.md'
  
  build:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Build documentation site
        run: |
          npm ci
          npm run docs:build
      
      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/.vitepress/dist

Cet exemple montre un pipeline complet qui valide la syntaxe Markdown, vérifie les liens cassés, contrôle l'orthographe, génère le site de documentation et le déploie automatiquement. Chaque pull request déclenche les validations, assurant la qualité avant fusion.

Mise en œuvre progressive

1. Choisir un format markup adapté (Markdown recommandé pour sa simplicité et adoption large)
2. Structurer l'arborescence de documentation dans le repository source (dossier /docs à la racine)
3. Sélectionner un générateur de site statique (VitePress, Docusaurus, MkDocs, Sphinx selon l'écosystème)
4. Configurer les validations automatiques (linting, link checking, spell checking) dans la CI
5. Établir des conventions de contribution (templates, guidelines de style, processus de revue)
6. Implémenter le déploiement automatique vers une plateforme d'hébergement (GitHub Pages, Netlify, Vercel)
7. Former l'équipe aux workflows et intégrer la documentation dans la definition of done

Outils et écosystème

• Générateurs de sites : VitePress (Vue), Docusaurus (React), MkDocs (Python), Hugo (Go), Sphinx (Python)
• Validation : markdownlint, markdown-link-check, cSpell, Vale (prose linting)
• Gestion des versions d'API : OpenAPI/Swagger, AsyncAPI pour documentation automatisée
• Diagrammes as Code : Mermaid, PlantUML, D2 intégrés directement dans Markdown
• Plateformes de déploiement : GitHub Pages, Netlify, Vercel, GitLab Pages, Read the Docs
• Collaboration : GitHub/GitLab pour revues, Conventional Commits pour traçabilité

L'adoption de Documentation as Code transforme la documentation d'une tâche administrative souvent négligée en un composant naturel du processus de développement. Cette approche réduit considérablement le fossé entre code et documentation, améliorant la qualité produit finale et l'expérience développeur. Les équipes constatent typiquement une réduction de 60% de la documentation obsolète et une augmentation significative de la contribution documentaire lorsque les barrières d'outils sont supprimées.