Exemple : une architecture de dépôt documentaire

Exemple abouti

Ceci est un exemple abouti à étudier, pas un modèle - les besoins exacts de chaque dépôt diffèrent. Pour la décision sous-jacente, voir le référentiel et un référentiel unique ?.

L’arborescence

depot-docs/
├── src/
│   ├── content/
│   │   ├── en/
│   │   │   ├── demarrage/
│   │   │   │   ├── index.md
│   │   │   │   ├── installation.md
│   │   │   │   └── premier-projet.md
│   │   │   ├── guides/
│   │   │   │   └── ...
│   │   │   └── reference/
│   │   │       └── ...
│   │   └── fr/
│   │       └── <reproduit l'arborescence en/>
│   ├── components/         # composants de page réutilisables
│   └── assets/              # images référencées depuis le contenu
├── scripts/                  # automatisation au moment du build (redirections, index de recherche, etc.)
├── tests/                    # vérifications automatisées sur la sortie du build
├── fichier-de-configuration   # configuration du site/build
└── manifeste-du-paquet

Pourquoi cette forme

• La langue est la division de premier niveau, pas un suffixe sur chaque nom de fichier (installation.md / installation.fr.md). Cela maintient chaque langue comme une arborescence complète et navigable indépendamment - voir traduction sur la façon dont une organisation langue-en-premier simplifie la gestion de branches pour un travail de traduction en parallèle.
• Le contenu est regroupé par intention du lecteur (demarrage/, guides/, reference/), pas par structure d’équipe interne ni par équipe produit propriétaire d’une page. Les lecteurs naviguent selon ce qu’ils essaient de faire, pas selon votre organigramme.
• scripts/ et tests/ sont séparés de content/. Un contributeur qui corrige une coquille n’a jamais besoin de regarder l’outillage de build, et un contributeur qui modifie le build ne touche pas la prose par accident.
• Les assets vivent à proximité de l’arborescence de contenu, pas dans un unique dossier images/ plat avec des milliers de fichiers - cela rend évident quelles images sont encore référencées quand une page est supprimée.

Ce qui n’a pas sa place dans ce dépôt

• La sortie générée (HTML compilé, PDF) - régénérez-la en CI, ne la committez pas. Une entrée .gitignore, pas un dossier, est le bon emplacement pour les artefacts de build.
• Les secrets ou identifiants pour tout service touché par le build (clés d’analytics, tokens de déploiement) - cela appartient au gestionnaire de secrets de la plateforme CI/CDCI/CD (intégration continue et livraison continue)Automatisation qui vérifie chaque modification dès qu'elle est proposée (intégration continue), puis publie le résultat une fois les contrôles réussis (livraison continue). En docs-as-code, un pipeline CI/CD compile la documentation, exécute des tests, comme la vérification des liens et des schémas, et déploie le site.Voir dans le glossaire →, jamais à des fichiers suivis.
• Les fichiers source binaires (voir format source) - si un asset ancien doit absolument rester binaire, gardez-le petit et traitez-le comme une exception, pas comme un modèle à reproduire.

Étape suivante

Pour voir comment une modification traverse un dépôt comme celui-ci, de la brancheBrancheLigne de travail parallèle dans un système de gestion de versions : les modifications faites sur une branche restent isolées jusqu'à leur relecture et leur fusion dans la ligne principale, ce qui permet de faire avancer en même temps plusieurs rédacteurs, versions ou langues.Voir dans le glossaire → à la page publiée, voir l’exemple de workflow docs-as-code.