Documentation en tant que code

1) Principes architecturaux

1. Une seule source de vérité. Documents, schémas, diagrammes, spécifications API, glossaire - dans VCS à côté du code.
2. Contrôle de qualité automatique. Linters, orthographe, vérification des liens, doctest exemples de code.
3. L'assemblage est comme un artefact. Le site Web, PDF/ebook, « conseils intégrés » fait partie de la version pipline.
4. Versioning et tracabilité. Doc règle le même PR qui modifie le comportement du système ; Les ADR sont liés aux commits.
5. Accessibilité par rôle. Public/interne, Runbook 'et sous on-call, API Specs pour intégrateurs.
6. Un minimum de travail manuel. Génération de tables des matières, schémas, graphes de dépendances, fragments de code - à partir de sources.

2) Types de documents et structure de repo

docs/
index. md architecture/
overview. md contexts/( C4, contexts, boundaries)
components/
data/
schemas/ (JSON Schema, Avro, Proto)
lineage/ (dataflow. md, dq-policies. md)
security/
threat-models/
key-management. md api/
openapi/ (OpenAPI. yaml)
asyncapi/ (.yaml)
grpc/ (.proto)
processes/
rfc/ (RFC-YYYY-XX-Title. md)
adr/ (ADR-0001-title. md)
runbooks/ (incident-.md)
playbooks/
sops/ (standard operating procedures)
product/
user-guides/
how-to/
faq/
i18n/
en/, en/, tr/# assets localization/
diagrams/ (Mermaid, PlantUML, Graphviz)
images/
_templates/ (RFC/ADR/Runbook templates)

• RFC - Discuter des solutions avant leur mise en œuvre.
• ADR est une solution architecturale fixe (contexte → solution → conséquences de → alternatives).
• Runbook/Playbook - instructions étape par étape pour les incidents et les opérations.
• How-To/FAQ - Tâche → étapes → vérification des résultats.
• API Specs - OpenAPI/AsyncAPI/Proto comme source de génération de SDK et de docks.
• Les graphiques en tant que code sont des Mermaid/PlantUML/Graphviz/C4.

3) Style et normes

Un guide de style unique (ton, terminologie, modèles de titre, exemples).
Glossaire avec termes canoniques (EN/RU), alias, termes interdits.
Numérotation et références : ancres permanentes, références croisées entre ADR/RFC/code.

yaml title: "Payment Service: Overview"
owner: "payments-team"
reviewers: ["platform", "security"]
last_review: 2025-10-15 tags: ["architecture","payments","pci"]

4) Assemblage et publication

• MkDocs (Material) - simple, pratique, bonne navigation et la recherche.
• Docusaurus - version de la documentation et docs + blog ; Composants MDX.
• Antora est une documentation modulaire pour les grandes plates-formes.

yaml site_name: Platform Docs theme:
name: material features: [navigation. tabs, content. code. annotate, search. suggest]
plugins:
- search
- mermaid2
- mkdocs-awesome-pages-plugin
- macros nav:
- Review: index. md
- Architecture:
- Overview: architecture/overview. md
- Data: architecture/data/index. md
- API:
- REST: api/openapi/index. md
- Events: api/asyncapi/index. md

5) Diagrammes et schémas comme code

mermaid sequenceDiagram participant C as Client participant G as API Gateway participant S as Service
C->>G: POST /orders
G->>S: createOrder()
S-->>G: 201 + order_id
G-->>C: 201 Created

@startuml
!include <C4/C4_Container>
Person(user, "User")
System_Boundary(system, "Platform"){
Container(api, "API", "HTTP")
Container(db, "DB", "Postgres")
}
Rel(user, api, "Uses")
Rel(api, db, "CRUD")
@enduml

OpenAPI/AsyncAPI est rendu dans le site ; ils génèrent des SDK/clients/exemples.

6) Qualité : linters et tests de documentation

• markdownlint - règles de formatage Markdown.
• Vale - style/terminologie/ton.
• Spellcheck est une orthographe (dictionnaires RU/EN).
• Linkcheck - liens externes/internes, ancres.
• Doctest/Exemples - Exécution de fragments de code, synchronisation des versions CLI/API.
• Schematest est une validation OpenAPI/AsyncAPI/JSON Schema/Proto.

yaml name: docs-ci on: [pull_request, push]
jobs:
lint:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: npm i -g markdownlint-cli
- run: markdownlint "docs//.md"
- run: pipx run codespell docs          true
- run: pipx run linkchecker docs/site          true build:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
- run: pip install mkdocs-material mkdocs-mermaid2-plugin
- run: mkdocs build --strict preview:
if: github. event_name == 'pull_request'
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: mkdocs build
- uses: actions/upload-pages-artifact@v3

python docs/snippets/calc. py def add(a,b):
"""Returns sum of a and b.

>>> add(2,3)
5
"""
return a+b

CI lance 'python -m doctest docs/snippets/calc. py`.

7) Processus : RFC/ADR/révisions et SLA sur l'obsolescence

RFC flow : l'initiateur → un brouillon → une discussion → une décision → un plan → une mise en œuvre → un post-factuel rétro.
ADR flow : nous enregistrons brièvement la sélection + référence RFC/expériences.
Procédure de révision : la source est 'CODEOWNERS' + 'doc-owners. yaml`.
SLA sur l'obsolescence : les articles critiques ont « last _ review » et alert sur la rhubarbe après N jours.

markdown
ADR-0007: Select Event Log - Avro + Schema Registry
Date: 2025-10-31
Status: accepted
Context: the evolution of schemes without breaking consumers is required.
Solution: Avro + Schema Registry, backward compatibility.
Implications: tooling, compatibility tests, N services migration.
Alternatives: JSON Schema, Protobuf (rejected due to X/Y).

8) Localisation (i18n) et multilinguisme

Stratégie de localisation : langue source (EN ou RU) → traduction par les branches 'i18n/< locale>'.
Clés et contexte : stocker le « stable-ID » pour les titres/fragments.
Vérifications : étape 'missing-key', alertes de dissynchronisation.
Styles locaux : glossaires locaux, calques non valides, exemples de code en langage UI local.

9) Intégration avec le produit

Aide intégrée (in-app docs) : composants MDX, conseils contextuels.
Versioning par release : tags/branches 'docs/vX. Y ', un site avec un sélecteur de version.
Auto-génération de sections : à partir d'OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help'.
Changelog en tant que code : génération automatique par les étiquettes PR (feat/fix/docs/breaking).

10) Métriques et observabilité de la documentation

Docs SLO : temps de construction/publication, aptyme du site, temps d'apparition du document après PR.
Couverture par artefacts : proportion de services avec ADR, proportion d'endpoints avec exemples, proportion de Runbook avec « test de santé ».
Métriques personnalisées : requêtes de recherche sans réponses, profondeur de visualisation, CTR des indices intégrés.
Qualité : erreurs de linters/1000 lignes, « liens battus », proportion d'articles obsolètes.

11) Sécurité et vie privée

Les secrets et les DP sont interdits dans les repo ; linters sur les secrets et le masquage.
Accès au site interne par l'intermédiaire du SSO ; les sections publiques sont séparées.
Règles d'exportation : PDF/archives sans liens internes, filigranes pour les documents confidentiels.
Assainissement des captures d'écran : anonymisation automatique (données de la coq/blur).

12) Modèles

Docs in PR. Tout changement affectant le comportement implique la mise à jour des docks dans le même PR.
Les modèles sont comme un contrat. La création d'un service/endpoint/datacet - via un générateur qui dépose les pièces des docks.
Les graphiques sont comme un code. Toute figure est une source modifiable, un assemblage SVG/PNG dans CI.
Docs Preview. Commentaire du bot avec un lien vers la pré-projection du site pour PR.
Les liens sont dans le code. Annotations dans les sources ('@ doc : adr/0007') qui sont rendues dans le site.

13) Anti-modèles

Documentation dans wiki/Notification sans version à côté du code → dissynchronisation.
Les captures d'écran sans source → impossible de mettre à jour automatiquement.
Connaissances « secrètes » dans les chats oraux et les fichiers privés.
Génériques sans exemples et invariants → pages inutiles.
Absence de propriétaires et 'last _ review' → avalanche d'obsolescence.
L'assemblage manuel et la publication → la sortie fragile et rare des docks.

14) Exemples d'automatisation

bash build. sh scripts/render-openapi. sh api/openapi/.yaml > docs/api/openapi/index. md scripts/render-asyncapi. sh api/asyncapi/.yaml > docs/api/asyncapi/index. md

bash linkcheck --config. linkcheck. yml site/

yaml
- name: Deploy Preview run: mkdocs build && npx serve -s site -l 5000 &
- name: Comment with URL uses: peter-evans/create-or-update-comment@v4 with:
issue-number: ${{ github. event. pull_request. number }}
body: "Preview: http ://preview- $ {{github. run_id }}.local"

15) Chèque de l'architecte

1. Y a-t-il un seul référentiel de docks à côté du code et une structure compréhensible ?
2. Les modèles (RFC/ADR/Runbook/How-To) et le glossaire sont-ils décrits ?
3. Sont inclus les linters (markdownlint, Vale), spellcheck, linkcheck et doctest ?
4. Diagrammes et schémas - en tant que code, assemblé en IC ?
5. Les spacs API (OpenAPI/AsyncAPI/Proto) sont-ils validés et rendus sur le site ?
6. Organisé docs-preview pour PR et auto-publication sur merge ?
7. Y a-t-il un SLA sur l'obsolescence (last_review) et les « propriétaires » des pages ?
8. Métriques : couverture, erreurs de linters, liens battus, requêtes de recherche « zéro » ?
9. Politiques de sécurité : secrets interdits, SSO, filigranes/exportation ?
10. La localisation est gérée par les branches et vérifiée pour les passes ?

Conclusion

Docs-as-Code transforme la documentation de la « note post-factum » en un artefact de travail de développement : versionable, testée et livrable. Avec cette approche, les connaissances vivent à côté du code, les changements sont transparents et les utilisateurs et les ingénieurs reçoivent des instructions, des schémas et des exemples à jour quand ils sont nécessaires. Cela réduit les risques opérationnels, accélère l'onbording et améliore la qualité des solutions sur l'ensemble de la plateforme.