Documentation as Code

La documentation as code signifie traiter la documentation comme du code source : versionnée, revue, testée et déployée automatiquement. Une bonne docs-as-code maintient la documentation précise et à jour. Une mauvaise documentation devient obsolète et ignorée. Ce guide couvre l'implémentation de la docs-as-code.

Avantages de la docs-as-code

Implémentation

Configuration

CONFIGURATION DOCS-AS-CODE
══════════════════════════

STRUCTURE DU DÉPÔT :
─────────────────────────────────────
project/
├── src/
│   └── (code)
├── docs/
│   ├── getting-started.md
│   ├── api/
│   │   ├── endpoints.md
│   │   └── authentication.md
│   ├── guides/
│   │   ├── setup.md
│   │   └── deployment.md
│   └── reference/
│       └── configuration.md
├── README.md
└── CONTRIBUTING.md

OUTILLAGE :
─────────────────────────────────────
Écriture :
├── Markdown (le plus courant)
├── AsciiDoc (plus de fonctionnalités)
├── reStructuredText
└── Format texte brut

Construction :
├── MkDocs (Python)
├── Docusaurus (React)
├── Hugo (Go)
├── Astro (moderne)
├── VuePress
└── Générateur de site statique

CI/CD :
├── Build sur PR
├── Déploiements preview
├── Déployer sur merge
├── Pipeline automatisé
└── Comme le code

Workflow

Processus de documentation

WORKFLOW DOCS-AS-CODE
═════════════════════

ÉCRITURE :
─────────────────────────────────────
1. Créer branche
   git checkout -b docs/add-api-guide

2. Écrire docs
   Éditer docs/api/new-feature.md

3. Preview local
   mkdocs serve

4. Commit
   git add docs/
   git commit -m "docs: add API guide"

5. Push et PR
   git push origin docs/add-api-guide

REVUE :
─────────────────────────────────────
La PR inclut :
├── Vérification précision du contenu
├── Revue technique
├── Validation des liens
├── Cohérence du style
├── Déploiement preview
└── Comme la revue de code

DÉPLOIEMENT :
─────────────────────────────────────
Sur merge :
├── CI build les docs
├── Site statique généré
├── Déployé sur l'hébergement
├── En ligne en minutes
├── Automatisé
└── Pas d'étapes manuelles

Maintenir les docs à jour

Maintenance de la documentation

GARDER LES DOCS À JOUR
══════════════════════

DOCS DANS LA MÊME PR :
─────────────────────────────────────
Quand on change le code :
├── Mettre à jour docs pertinentes
├── Même PR, même revue
├── Impossible d'oublier
├── Changement atomique
└── Meilleure pratique

DÉFINITION DE DONE :
─────────────────────────────────────
DoD inclut :
├── ☐ Code complet
├── ☐ Tests passent
├── ☐ Docs mises à jour ← Requis
├── ☐ Revu
└── Docs pas optionnel

VÉRIFICATIONS AUTOMATISÉES :
─────────────────────────────────────
Vérifications CI :
├── Détection liens cassés
├── Linting Markdown
├── Vérification orthographe
├── Succès du build
└── Validation du style

Formats et standards

Conventions Markdown

Établir des conventions de documentation aide à maintenir la cohérence à travers l'équipe. Définissez des standards pour les niveaux de titres, les blocs de code, les liens et les images. Utilisez des linters comme markdownlint pour faire respecter ces conventions automatiquement.

Templates de documentation

Créez des templates pour les types de documents courants : documentation API, guides, tutoriels, notes de release. Les templates assurent la cohérence et réduisent le temps pour créer de nouvelles documentations. Stockez les templates dans le dépôt pour un accès facile.

Intégration avec GitScrum

GitScrum s'intègre avec les workflows docs-as-code en reliant les tâches de documentation aux user stories et fonctionnalités. Les équipes peuvent suivre le travail de documentation aux côtés du développement, assurant que les docs sont incluses dans la planification de sprint et les mesures de vélocité.

NoteVault fournit un emplacement central pour la documentation qui ne vit pas dans le code - notes d'architecture, décisions, et guides d'onboarding. Combiné avec les dépôts docs-as-code, les équipes ont une couverture complète de la documentation.

Solutions connexes

• Bonnes pratiques de documentation
• Documentation des décisions architecturales
• Base de connaissances développeur