Documentação como código

1) Princípios arquitetônicos

1. Uma única fonte de verdade. Documentos, esquemas, diagramas, especificações de API, glossário - em VCS ao lado do código.
2. Verificação automática de qualidade. Linteres, ortografia, links, doctest exemplos de código.
3. Montagem como artefacto. Dock site, PDF/ebook, «dicas incorporadas» faz parte do pipline de lançamento.
4. Versionização e rastreabilidade. O doutor governa o mesmo PR, o que altera o comportamento do sistema; Os ADR estão ligados a comitivas.
5. Disponibilidade por papel. Público/interno, Runbook 'e sob on-call, API spacks para integradores.
6. Pelo menos feito à mão. Geração de sumários, esquemas, gráficos de dependências, fatias de código - a partir de fontes.

2) Tipos de documentos e estrutura 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 - discutir soluções antes da implementação.
• ADR é uma solução arquitetônica fixada (contexto → solução → consequências → alternativa).
• Runbook/Playbook - instruções passo a passo para incidentes e operações.
• How-To/FAQ - a tarefa é → os passos → verificar o resultado.
• API speki - OpenAPI/AsyncAPI/Proto como fonte de geração de SDK e docas.
• Diagramas como código - Mermaid/PlantUML/Graphviz/C4.

3) Estilo e padrões

Guia de estilo único (tom, terminologia, modelos de cabeçalho, exemplos).
Glossário com termos canônicos (EN/RU), aliasas, termos proibidos.
Numeração e links: ancoras permanentes, cruzados 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) Montagem e publicação

• MkDocs (Material) - simples, conveniente, boa navegação e pesquisa.
• Docusaurus - Versionamento de documentação e docs + blog; componentes MDX.
• Antora - documentação 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 e esquemas 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 são rendidos para o site; destes, são gerados SDK/clientes/exemplos.

6) Qualidade: linteres e testes de documentação

• markdownlint - regras de formatação do Markdown.
• Vale - estilo/terminologia/tom.
• Spellcheck - ortografia (dicionários RU/EN).
• Linkcheck - links externos/internos, âncoras.
• Doctest/Excamples - execução de fragmentos de código, sincronização de versões CLI/API.
• Schematest - validação 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 lança 'python -m doctest docs/snippets/calc. py`.

7) Processos: RFC/ADR/revisões e SLA para obsolescência

RFC flow: iniciador → rascunho → discussão → decisão → plano → implementação → pós-faturamento retrô.
ADR flow: gravamos brevemente a seleção + link RFC/experimentos.
Procedimentos Review: Origem: 'CODEOWNERS' + 'doc-owners. yaml`.
SLA à obsolescência: artigos críticos têm 'last _ review' e alert ao revezamento em N dias.

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) Localização (i18n) e multilinguismo

Estratégia de localização: língua original (EN ou RU) → tradução de ramais 'i18n/< local>'.
Chave e contexto: Armazenando «ID-stable» para cabeçalhos/fragmentos.
Verificações: Passo 'missing-keys', alertas de descolonização.
Estilos de local: glossários locais, calcanhares inválidos, exemplos de código UI local.

9) Integração com o produto

Ajuda incorporada (in-app docs): componentes MDX, dicas contextuais.
Versioning por lançamentos: tags/ramais 'docs/vX. Y ', um site com versões selectores.
Geração automática de seções: de OpenAPI/AsyncAPI, GraphQL SDL, CLI '-help'.
Changelog como código: geração automática por rótulos PR (feat/fix/docs/breaking).

10) Métricas e observabilidade da documentação

Docs SLO: tempo de montagem/publicação, farmácia do site, hora de entrada do documento após PR.
Revestimento de artefatos: proporção de serviços com ADR, proporção de endpoint com exemplos, proporção de Runbook's com «teste de saúde».
Métricas personalizadas: buscas sem resposta, profundidade de visualização, CTR de dicas incorporadas.
Qualidade: erros de linter/1000 linhas, referências batidas, proporção de artigos obsoletos.

11) Segurança e privacidade

Segredos e PD são proibidos no repo; linteres para segredos e camuflagem.
Acesso ao site interno por SSO; as seções públicas estão separadas.
As regras de exportação são PDF/arquivos sem links internos, marcas de água para documentos confidenciais.
Saneamento de capturas de tela: anonimato automático (MK/blur).

12) Pattern

Docs in PR. Qualquer alteração que afete o comportamento inclui atualização das docas no mesmo PR.
Os modelos são como um contrato. Criar um serviço/endpoint/dataset - através de um gerador que coloca peças docas.
Diagramas como código. Qualquer imagem é um fonte editável, uma montagem SVG/PNG em CI.
Docs Preview. Comentário do bot com referência a pré-teste do site para PR.
O Dr. Links está no código. Anotações de origem ('@ doc: adr/0007') que são rendidas para o site.

13) Anti-pattern

Documentação no wiki/Notion sem versões ao lado do código → descolonização.
As telas de tela sem origem → que você não pode atualizar automaticamente.
Conhecimento secreto em áudios e arquivos privados.
Gerativos sem exemplos ou invariantes → páginas inúteis.
A ausência de proprietários e 'last _ review' → uma avalanche de obsolescência.
Montagem manual e publicação → lançamentos fracos e raros de docas.

14) Exemplos de automação

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) Folha de cheque do arquiteto

1. Existe um repositório único de docas junto ao código e uma estrutura compreensível?
2. Os modelos (RFC/ADR/Runbook/How-To) e o glossário são descritos?
3. Linkcheck (markdownlint, Vale), spellcheck, linkcheck e doctest incluídos?
4. Diagramas e esquemas - como código, montagem em CI?
5. Os API speks (OpenAPI/AsyncAPI/Proto) são validados e rendidos para o site?
6. Organizado por docs-preview para PR e publicação automática por merge?
7. Há SLA para obsolescência (last _ review) e «proprietários» de páginas?
8. Métricas: revestimento, erros de linter, links batidos, pesquisas «zero»?
9. Políticas de segurança: segredos proibidos, SSO, marcas de água/exportação?
10. A localização é controlada por ramais e verificada por omissões?

Conclusão

O docs-as-Code transforma a documentação de «notas postas» em um artefato de trabalho de desenvolvimento versionável, testado e entregue. Com esta abordagem, o conhecimento vive perto do código, as alterações são transparentes e os usuários e engenheiros recebem instruções, esquemas e exemplos relevantes quando eles são necessários. Isso reduz os riscos operacionais, acelera a negociação e melhora a qualidade das soluções em toda a plataforma.