Documentazione come codice

1) Principi architettonici

1. Un'unica fonte di verità. Documenti, schemi, grafici, specifiche API, glossario - in VCS accanto al codice.
2. Controllo di qualità automatico. Lintern, ortografia, controllo dei collegamenti, doctest degli esempi di codice.
3. Assemblaggio come artefatto. Il sito doc, PDF/ebook, i suggerimenti incorporati fanno parte del pipline di lancio.
4. Versioning e tracciabilità. Doc governa la stessa PR, che cambia il comportamento del sistema; Gli ADR sono collegati ai committenti.
5. Disponibilità per ruolo. Pubblico/interno, Runbook e sotto on-call, API per integratori.
6. Almeno fatto a mano. Generazione di sommari, diagrammi, grafici di dipendenze, frammenti di codice da sorgenti.

2) Tipi di documento e struttura di 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 - Discussione sulle soluzioni prima dell'implementazione.
• ADR è una soluzione architettonica fissata (contesto, soluzione e impatto dell'alternativa).
• Runbook/Playbook - istruzioni passo passo per incidenti e operazioni.
• How-To/FAQ è il compito di i passi per verificare il risultato.
• API - OpenAPI/AsyncAPI/Proto come fonte di generazione SDK e molo.
• I diagrammi sono un codice Mermaid/PlantUML/Graphviz/C4.

3) Stile e standard

Guida unica allo stile (tonalità, terminologia, modelli di intestazione, esempi).
Glossario con termini canonici (EN/RU), aliasi, termini proibitivi.
Numerazione e riferimenti: Ancoraggi permanenti, crocifissi tra ADR/RFC/codice.

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

4) Assemblaggio e pubblicazione

• MkDocs - semplice, comodo, buona navigazione e ricerca.
• Docusaurus - Versione documentazione e docs + blog; componenti MDX.
• Antora è una documentazione modulare per piattaforme di grandi dimensioni.

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) Diagrammi e diagrammi come codice

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

Sono OpenAPI/AsyncAPI nel sito; di questi vengono generati SDK/client/esempi.

6) Qualità: lenti e test di documentazione

• markdownlint - le regole di formattazione di Markdown.
• Valle - stile/terminologia/tono.
• Spellcheck - ortografia (dizionari RU/EN).
• Linkcheck è un collegamento esterno/interno, ancoraggio.
• Doctest/Examples - Esecuzione di frammenti di codice, sincronizzazione delle versioni CLI/API.
• Schematest - convalida di 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 avvia il'python -m docest docs/snippets/calc. py`.

7) Processi: RFC/ADR/recensioni e SLA per l'obsolescenza

RFC flow - Iniziatore della bozza, discussione, decisione, piano, implementazione, post-fattura retrò.
ADR flow: registra brevemente la selezione + link RFC/esperimenti.
Procedure di review: sorgente: "CODEOWNERS" + "doc-owners. yaml`.
SLA per l'obsolescenza: gli articoli critici hanno «last _ review» e alert per la gelosia dopo n giorni.

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) Localizzazione (i18n) e multilingue

Strategia di localizzazione: la lingua di origine (EN o RU) viene tradotta in «i18n/< locale>».
Chiave e contesto - Memorizza l'ID stable per le intestazioni o le porzioni.
Controlli: passo «missing-keys», alert per la rassincronizzazione.
Stili locali: glossari locali, calci non validi, esempi di codice UI locale.

9) Integrazione con il prodotto

Guida incorporata (in-app docs): componenti MDX, suggerimenti contestuali.
Versioning per rilascio tag/rami "docs/vX. Y ', il sito con le versioni selector.
Generazione automatica delle sezioni da OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help'.
Changelog come codice: generazione automatica con etichette PR (feat/fix/docs/breaking).

10) Metriche e osservabilità della documentazione

Docs SLO: tempo di assemblaggio/pubblicazione, farmacie del sito, ora di comparsa del documento dopo PR.
Copertura di manufatti: la quota di servizi con ADR, la percentuale di endpoint con esempi, la quota di Runbook con «controllo sanitario».
Metriche personalizzate: ricerche senza risposta, profondità di visualizzazione, suggerimenti integrati CTR.
Qualità: errori linter/1000 righe, riferimenti a bit, percentuale di articoli obsoleti.

11) Sicurezza e privacy

Segreti e PD sono vietati nel repo; Lintern per segreti e occultamento.
Accesso al sito interno tramite SSO; partizioni pubbliche separate.
Regole di esportazione: PDF/archivi senza collegamenti interni, filigrane per documenti sensibili.
Igiene degli screenshot - Anonimizzazione automatica (CIO/blur).

12) Pattern

Docs in PR. Tutte le modifiche che influiscono sul comportamento includono l'aggiornamento del molo nella stessa PR.
Modelli come contratto. Crea un servizio/endpoint/dataset tramite un generatore che posiziona i pezzi in lavorazione.
Diagrammi come codice. Ogni immagine è un sorgente modificabile, un assieme SVG/PNG in CI.
Docs Preview. Commento bot con riferimento all'anteprima del sito per PR.
Il doc è nel codice. Annotazioni di origine ('@ doc: adr/0007') che vengono rese al sito.

13) Anti-pattern

Documentazione in wiki/Notion senza versioni accanto al codice di disincronizzazione.
Gli screenshot senza sorgente non possono essere aggiornati automaticamente.
Conoscenza «segreta» nelle chat orali e nei file privati.
I generici senza esempi e invarianti sono pagine inutili.
Nessun proprietario e 'last _ review', valanga di obsolescenza.
Assemblaggio manuale e pubblicazione di una release del molo leggera e rara.

14) Esempi di automazione

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) Assegno-foglia architetto

1. Esiste un unico repository del molo vicino al codice e una struttura comprensibile?
2. Sono stati descritti i modelli (RFC/ADR/Runbook/How-To) e il glossario?
3. Sono inclusi linker (markdownlint, Valle), spellcheck, linkcheck e doctest?
4. Diagrammi e schemi - come codice, assemblaggio in CI?
5. Gli API sono validi e resi al sito?
6. È stato organizzato un docs-preview per PR e una pubblicazione automatica per merge?
7. Ci sono SLA per l'obsolescenza (last _ review) e «proprietari» di pagine?
8. Metriche: copertura, errori dei linter, collegamenti a bit, ricerche zero?
9. Regole di sicurezza: segreti proibiti, SSO, filigrana/esportazione?
10. La localizzazione è controllata dai rami e verificata dai passaggi?

Conclusione

Docs-as-Code trasforma la documentazione da «post-note» in un artefatto di sviluppo di lavoro, versionabile, testabile e da consegnare. Con questo approccio, la conoscenza vive accanto al codice, le modifiche sono trasparenti e gli utenti e gli ingegneri ricevono istruzioni, schemi e esempi aggiornati quando ne hanno bisogno. Ciò riduce i rischi operativi, accelera l'onboarding e migliora la qualità delle soluzioni in tutta la piattaforma.