Documentation as code

1) Architectural principles

1. A single source of truth. Documents, diagrams, diagrams, API specifications, glossary - in VCS next to the code.
2. Automatic quality check. Linters, spelling, link checking, doctest code examples.
3. Assembly as artifact. Docking site, PDF/ebook, "built-in hints" - part of the release pipeline.
4. Versioning and traceability. Doc rules the same PR that changes the behavior of the system; ADRs are commit-bound.
5. Availability by role. Public/internal, Runbook 'and on-call, API specs for integrators.
6. Handmade minimum. Generation of tables of contents, diagrams, dependency graphs, code fragments - from sources.

2) Document types and repo structure

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 - Discuss solutions before implementation.
• ADR - fixed architectural solution (context → solution → consequences of → alternative).
• Runbook/Playbook - step-by-step instructions for incidents and operations.
• How-To/FAQ - task → steps → check the result.
• API specs - OpenAPI/AsyncAPI/Proto as a source of SDK generation and docks.
• Diagrams as code - Mermaid/PlantUML/Graphviz/C4.

3) Style and standards

Single style guide (tone, terminology, title templates, examples).
Glossary with canonical terms (EN/RU), aliases, forbidden formulations.
Numbering and references: permanent anchors, cross references between ADR/RFC/code.

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

4) Assembly and publication

• MkDocs (Material) - simple, convenient, good navigation and search.
• Docusaurus - documentation version and docs + blog; MDX components.
• Antora - modular documentation for large platforms.

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) Diagrams and diagrams as 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 are rendered to the site; SDK/clients/examples are generated from them.

6) Quality: linters and documentation tests

• markdownlint - Markdown formatting rules.
• Vale - style/terminology/tone.
• Spellcheck - spelling (RU/EN dictionaries).
• Linkcheck - external/internal links, anchors.
• Doctest/Examples - executing code snippets, synchronizing CLI/API versions.
• Schematest - OpenAPI/AsyncAPI/JSON Schema/Proto validation.

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

7) Processes: RFC/ADR/Reviews and SLAs for obsolescence

RFC flow: initiator → draft copy → discussion → decision → plan → implementation → retro post facto.
ADR flow: briefly fix the choice + reference to RFC/experiments.
Review procedures: source - 'CODEOWNERS' + 'doc-owners. yaml`.
SLA for obsolescence: critical articles have 'last _ review' and alert for review in N days.

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) Localization (i18n) and multilingualism

Localization strategy: source language (EN or RU) → translation by branches' i18n/< locale> '.
Keys and context: store "stable-ID" for headers/fragments.
Checks: step 'missing-keys', alerts for desynchronization.
Locale styles: local glossaries, invalid tracing paper, examples of code in the local UI language.

9) Product integration

Built-in help (in-app docs): MDX components, context hints.
Versioning by release: tags/branches' docs/vX. Y ', a site with selector versions.
Auto-generation of sections: from OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help'.
Changelog as code: automatic generation by PR labels (feat/fix/docs/breaking).

10) Metrics and observability of documentation

Docs SLO: build/publish time, site uptime, time of document appearance after PR.

Artifact coverage: share of services with ADRs, share of endpoints with examples, share of Runbooks with "health checks."

User metrics: unanswered searches, viewing depth, CTR of built-in prompts.
Quality: linter errors/1000 lines, "broken links," the proportion of outdated articles.

11) Security and privacy

Secrets and PD are prohibited in repos; linters for secrets and masking.
Access to the internal site via SSO; public sections separated.
Export rules: PDF/archives without internal links, watermarks for confidential documents.
Screenshot sanitation: automatic anonymization (mok data/blur).

12) Patterns

Docs in PR. Any change affecting behaviour involves updating the docks in the same PR.
Templates as contract. Creation of a service/endpoint/dataset - through a generator that puts dock blanks.
Charts as code. Any picture - editable source, SVG/PNG assembly in CI.
Docs Preview. Bot comment with link to site preview for PR.
Docking links in the code. Annotations in sources ('@ doc: adr/0007') that are rendered to the site.

13) Anti-patterns

Documentation in wiki/Notion without versions next to the code → out of sync.
Screenshots without sources → the inability to update automatically.
"Secret" knowledge in oral chats and private files.
Generics without examples and invariants → useless pages.
Lack of owners and 'last _ review' → an avalanche of obsolescence.
Manual assembly and publication → a fragile and rare release of docks.

14) Automation examples

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) Architect checklist

1. Is there a single repository of docks next to the code and a clear structure?
2. Templates (RFC/ADR/Runbook/How-To) and glossary described?
3. Linters included (markdownlint, Vale), spellcheck, linkcheck and doctest?
4. Diagrams and diagrams - like code, assembly in CI?
5. Are API specs (OpenAPI/AsyncAPI/Proto) validated and rendered to the site?
6. Organized docs-preview for PR and auto-publish by merge?
7. Are there aging SLAs (last_review) and "owners" of pages?
8. Metrics: coverage, linter errors, broken links, search "zero" queries?
9. Security policies: secrets banned, SSO, watermarks/exports?
10. Localization is controlled by branches and checked for omissions?

Conclusion

Docs-as-Code transforms documentation from "post-fact notes" into a working artifact of development: versioned, tested, and delivered. With this approach, knowledge lives next to the code, changes are transparent, and users and engineers receive up-to-date instructions, diagrams and examples when they are needed. This reduces operational risks, speeds onboarding and improves the quality of solutions across the platform.