Documentație ca cod

1) Principii arhitecturale

1. O singură sursă de adevăr. Documente, diagrame, diagrame, specificații API, glosar - în VCS lângă cod.
2. Verificarea automată a calității. Lintere, ortografie, verificarea link-ului, exemple de coduri doctest.
3. Asamblarea ca artefact. Andocare site-ul, PDF/ebook, „built-in indicii” - parte a conductei de eliberare.
4. Versioning și trasabilitate. Doc conduce același PR care schimbă comportamentul sistemului; RAM sunt obligate să se angajeze.
5. Disponibilitate după rol. Public/intern, Runbook "și de gardă, specificații API pentru integratori.
6. Minimă lucrată manual. Generarea de tabele de conținut, diagrame, grafice de dependență, fragmente de cod - din surse.

2) Tipuri de documente și structura 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 - Discutați soluții înainte de implementare.
• ADR - soluție arhitecturală fixă (context → soluție → consecințele → alternative).
• Runbook/Playbook - instrucțiuni pas cu pas pentru incidente și operațiuni.
• How-To/FAQ - sarcină → pași → a verifica rezultatul.
• Specificații API - OpenAPI/AsyncAPI/Proto ca sursă de generare și docuri SDK.
• Diagrame ca cod - Mermaid/PlantUML/Graphviz/C4.

3) Stil și standarde

Ghid de stil unic (ton, terminologie, șabloane de titlu, exemple).
Glosar cu termeni canonici (EN/RU), pseudonime, formulări interzise.
Numerotare și referințe: ancore permanente, referințe încrucișate între ADR/RFC/cod.

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

4) Adunarea și publicarea

• MkDocs (Material) - navigare și căutare simplă, convenabilă și bună.
• Docusaurus - versiune documentație și docs + blog; Componente MDX.
• Antora - documentație modulară pentru platforme mari.

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) Diagrame și diagrame ca cod

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 sunt redate site-ului; SDK/clienți/exemple sunt generate de la ei.

6) Calitate: lintere și teste de documentație

• markdownlint - Markdown reguli de formatare.
• Vale - stil/terminologie/ton.
• Verificarea ortografiei (dicționare RU/EN).
• Linkcheck - link-uri externe/interne, ancore.
• Doctest/Exemple - executarea fragmentelor de cod, sincronizarea versiunilor CLI/API.
• Schema - OpenAPI/AsyncAPI/JSON Schema/Proto validare.

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 ruleaza 'python -m doctest docs/snippets/calc. py '.

7) Procese: RFC/ADR/Recenzii și SLA-uri pentru obsolescență

Flux RFC: inițiator proiect copie discuție decizie planificare implementare retro post facto.
Fluxul ADR: fixați pe scurt alegerea + referința la RFC/experimente.
Proceduri de revizuire: sursa - "CODEOWNERS" + "doc-proprietarii. yaml'.
SLA pentru obsolescență: articolele critice au „last _ review” și alertă pentru revizuire în zilele N.

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) Localizare (i18n) și multilingvism

Strategia de localizare: limbajul sursă (EN sau RU) → traducerea prin ramuri 'i18n/< locale>'.
Chei și context: stocați „ID-ul stabil” pentru antete/fragmente.
Verificări: pasul „chei lipsă”, alerte pentru desincronizare.
Stiluri locale: glosare locale, hârtie de urmărire nevalidă, exemple de cod în limba interfeței locale.

9) Integrarea produselor

Ajutor încorporat (documente în aplicație): componente MDX, indicii de context.
Versioning by release: tags/ramuri 'docs/vX. Y ', un site cu versiuni selectoare.
Generarea automată a secțiunilor: de la OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help'.
Changelog ca cod: generarea automată de etichete PR (feat/fix/docs/breaking).

10) Măsurarea și observabilitatea documentației

Docs SLO: construi/publica timp, uptime site-ul, timp de aspect document după PR.
Acoperire artefact: ponderea serviciilor cu ADR-uri, ponderea punctelor finale cu exemple, ponderea Runbooks cu „controale de sănătate”.
Măsurători ale utilizatorilor: căutări fără răspuns, adâncime de vizualizare, CTR a solicitărilor încorporate.
Calitate: erori de linter/1000 linii, „link-uri rupte”, proporția de articole învechite.

11) Securitate și confidențialitate

Secretele și PD sunt interzise în repos; lintere pentru secrete și mascare.
Accesul la site-ul intern prin SSO; secțiuni publice separate.
Reguli de export: PDF/arhive fără legături interne, filigrane pentru documente confidențiale.
Salubrizare prin captură de ecran: anonimizare automată (mok data/blur).

12) Modele

Docs în PR. Orice modificare care afectează comportamentul implică actualizarea docurilor în același PR.
Șabloane ca contract. Crearea unui serviciu/endpoint/set de date - printr-un generator care pune gloanțe oarbe de andocare.
Diagrame ca cod. Orice imagine - sursă editabilă, ansamblu SVG/PNG în CI.
Docs Preview. Bot comentariu cu link la previzualizare site-ul pentru PR.
Link-uri de andocare în cod. Adnotări în surse ('@ doc: adr/0007') care sunt redate site-ului.

13) Anti-modele

Documentație în wiki/noțiune fără versiuni lângă cod → în afara sincronizării.
Capturi de ecran fără surse → incapacitatea de a actualiza automat.
Cunoștințe „secrete” în chat-uri orale și fișiere private.
Generice fără exemple și invarianți → pagini inutile.
Lipsa proprietarilor și „last _ review” → o avalanșă de obsolescență.
Asamblarea și publicarea manuală → o eliberare fragilă și rară a docurilor.

14) Exemple de automatizare

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) Lista de verificare arhitect

1. Există un singur depozit de docuri lângă cod și o structură clară?
2. Șabloane (RFC/ADR/Runbook/How-To) și glosar descrise?
3. Linters incluse (markdownlint, Vale), spellcheck, linkcheck și doctest?
4. Diagrame și diagrame - cum ar fi codul, asamblarea în CI?
5. Specificațiile API (OpenAPI/AsyncAPI/Proto) sunt validate și redate site-ului?
6. Organizat docs-preview pentru PR și auto-publica prin fuziune?
7. Există SLA-uri îmbătrânite (last_review) și „proprietari” de pagini?
8. Valori: acoperire, erori de linter, link-uri rupte, căutare „zero” interogări?
9. Politici de securitate: secrete interzise, SSO, filigrane/exporturi?
10. Localizarea este controlată de ramuri și verificată pentru omisiuni?

Concluzie

Docs-as-Code transformă documentația din „note post-fapt” într-un artefact de lucru al dezvoltării: versionat, testat și livrat. Cu această abordare, cunoștințele trăiesc lângă cod, schimbările sunt transparente, iar utilizatorii și inginerii primesc instrucțiuni actualizate, diagrame și exemple atunci când sunt necesare. Acest lucru reduce riscurile operaționale, accelerează îmbarcarea și îmbunătățește calitatea soluțiilor pe întreaga platformă.