Documentación como código

1) Principios arquitectónicos

1. Una sola fuente de verdad. Documentos, esquemas, gráficos, especificaciones de API, glosario - en VCS junto al código.
2. Control de calidad automático. Linters, ortografía, validación de enlaces, doctest de ejemplos de código.
3. Ensamblaje como artefacto. El sitio del dock, PDF/ebook, «pistas integradas» es parte de la pipeline de lanzamiento.
4. Versificación y trazabilidad. El muelle gobierna el mismo PR, que cambia el comportamiento del sistema; Los ADR están enlazados a los commits.
5. Disponibilidad por roles. Público/interno, Runbook 'y debajo de la llamada, API-speks para integradores.
6. Un mínimo hecho a mano. Generar tablas de contenido, esquemas, grafos de dependencia, fragmentos de código - a partir de fuentes.

2) Tipos de documentos y estructura de repos

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 - Discusión de soluciones antes de la implementación.
• ADR es una solución arquitectónica fija (contexto → decisión → consecuencias de → alternativa).
• Runbook/Playbook - instrucciones paso a paso para incidentes y operaciones.
• How-To/FAQ es la tarea de → los pasos → verificar el resultado.
• API-speks - OpenAPI/AsyncAPI/Proto como fuente de generación de SDK y muelles.
• Diagramas como código - Mermaid/PlantUML/Graphviz/C4.

3) Estilo y estándares

Una sola guía de estilo (tono, terminología, plantillas de título, ejemplos).
Glosario con términos canónicos (EN/RU), alias, lenguaje prohibido.
Numeración y referencias: anclajes permanentes, referencias cruzadas entre ADR/RFC/código.

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

4) Compilación y publicación

• MkDocs (Material) - simple, conveniente, buena navegación y búsqueda.
• Docusaurus - versión de documentación y docs + blog; Componentes MDX.
• Antora es una documentación modular para grandes plataformas.

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) Diagramas y diagramas como código

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 son renderizados en el sitio; a partir de ellos se generan SDK/clientes/ejemplos.

6) Calidad: linternas y pruebas de documentación

• markdownlint - Reglas de formato de Markdown.
• Vale - estilo/terminología/tono.
• Spellcheck - ortografía (diccionarios RU/EN).
• Linkcheck - referencias externas/internas, anclas.
• Doctest/Samples - Ejecución de fragmentos de código, sincronización de versiones CLI/API.
• Schematest - validación 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 inicia 'python -m doctest docs/snippets/calc. py`.

7) Procesos: RFC/ADR/revisiones y SLA por obsolescencia

RFC flow: el iniciador → el borrador → la discusión → la decisión → el plan → implementatsiya → el puesto-faktum del retro.
ADR flow: fijamos brevemente la selección + referencia a RFC/experimentos.
Procedimientos de revisión: la fuente es 'CODEOWNERS' + 'doc-owners. yaml`.
SLA para la obsolescencia: los artículos críticos tienen 'last _ review' y una alerta para rugir después de N días.

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) Localización (i18n) y multilingüismo

Estrategia de localización: idioma de origen (EN o RU) → traducción por ramas 'i18n/< locale>'.
Claves y contexto: almacena «stable-ID» para encabezados/fragmentos.
Verificaciones: paso 'missing-keys', alertas para la rissincronización.
Estilos locales: glosarios locales, calcas no válidas, ejemplos de código en lenguaje local de IU.

9) Integración con el producto

Ayuda integrada (in-app docs): componentes MDX, sugerencias contextuales.
Versificación por lanzamientos: etiquetas/ramas 'docs/vX. Y ', un sitio con selector de versiones.
Autogeneración de secciones: desde OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help'.
Changelog como código: generación automática por etiquetas PR (feat/fix/docs/breaking).

10) Métricas y observabilidad de la documentación

Docs SLO: tiempo de compilación/publicación, aptime del sitio, tiempo de aparición del documento después de PR.
Cobertura con artefactos: proporción de servicios con ADR, proporción de endpoints con ejemplos, proporción de Runbook's con «chequeo de salud».
Métricas personalizadas: consultas de búsqueda sin respuestas, profundidad de navegación, CTR de sugerencias integradas.
Calidad: errores de linternas/1000 líneas, «enlaces rotos», proporción de artículos obsoletos.

11) Seguridad y privacidad

Los secretos y el PD están prohibidos en el repo; linternas de secretos y enmascaramiento.
Acceso al sitio interno a través de SSO; las secciones públicas están separadas.
Reglas de exportación: PDF/archivos sin referencias internas, marcas de agua para documentos confidenciales.
Saneamiento de capturas de pantalla: anonimización automática (datos moc/blur).

12) Patrones

Docs in PR. Cualquier cambio que afecte al comportamiento incluye la actualización de los muelles en el mismo PR.
Las plantillas son como un contrato. Creación de un servicio/endpoint/dataset - a través de un generador que pone las piezas de trabajo de los muelles.
Gráficos como código. Cualquier imagen es un origen editable, un conjunto SVG/PNG en CI.
Docs Preview. Comentario del bot con un enlace a la vista previa del sitio para PR.
Los acoplamientos están en código. Anotaciones en las fuentes ('@ doc: adr/0007') que se presentan en el sitio.

13) Anti-patrones

Documentación en wiki/Notion sin versiones junto al código → resincronización.
Las capturas de pantalla sin fuentes → la imposibilidad de actualizar automáticamente.
Conocimiento «secreto» en chats orales y archivos privados.
Los genéricos sin ejemplos e invariantes → páginas inútiles.
La falta de propietarios y 'last _ review' → una avalancha de obsolescencia.
Montaje y publicación manual → un lanzamiento de muelles quebradizo y raro.

14) Ejemplos de automatización

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) Check-list del arquitecto

1. ¿Hay un único repositorio de muelles junto al código y una estructura comprensible?
2. ¿Se describen las plantillas (RFC/ADR/Runbook/How-To) y el glosario?
3. ¿Están incluidos los linderos (markdownlint, Vale), spellcheck, linkcheck y doctest?
4. Diagramas y diagramas - ¿Cómo está el código, el ensamblaje en CI?
5. ¿Las APIs (OpenAPI/AsyncAPI/Proto) están validadas y renderizadas en el sitio?
6. Organizado docs-vista previa para PR y auto-publicación sobre merge?
7. ¿Hay un SLA de obsolescencia (last_review) y «propietarios» de páginas?
8. Métricas: cobertura, errores de linternas, enlaces rotos, consultas de búsqueda «cero»?
9. Políticas de seguridad: secretos prohibidos, SSO, marcas de agua/exportación?
10. ¿La localización se controla por ramas y se comprueba por saltos?

Conclusión

Docs-as-Code transforma la documentación de «notas a posteriori» en un artefacto de desarrollo de trabajo: versionable, probado y entregado. Con este enfoque, el conocimiento vive cerca del código, los cambios son transparentes y los usuarios e ingenieros reciben instrucciones, esquemas y ejemplos actualizados cuando son necesarios. Esto reduce los riesgos operativos, acelera el onboarding y mejora la calidad de las soluciones en toda la plataforma.