Dokumentacja jako kod

1) Zasady architektoniczne

1. Jedno źródło prawdy. Dokumenty, schematy, schematy, specyfikacje API, słownik - w VCS obok kodu.
2. Automatyczna kontrola jakości. Linters, pisownia, sprawdzanie linków, przykłady kodów doktorskich.
3. Zgromadzenie jako artefakt. Miejsce dokowania, PDF/ebook, „wbudowane wskazówki” - część rurociągu uwalniającego.
4. Wersioning i identyfikowalność. Doc rządzi tym samym PR, który zmienia zachowanie systemu; ADR są związane zobowiązaniami.
5. Dostępność według roli. Publiczne/wewnętrzne, Runbook'i dyżur, specyfikacje API dla integratorów.
6. Ręcznie wykonane minimum. Generowanie tabel treści, diagramów, wykresów zależności, fragmentów kodu - ze źródeł.

2) Rodzaje dokumentów i struktura 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 - Omówienie rozwiązań przed wdrożeniem.
• ADR - stałe rozwiązanie architektoniczne (kontekst → rozwiązanie → konsekwencje → alternatywa).
• Runbook/Playbook - instrukcje krok po kroku dotyczące incydentów i operacji.
• Jak-To/FAQ - zadanie → kroki → sprawdź wynik.
• Specyfikacje API - OpenAPI/AsyncAPI/Proto jako źródło generacji i doków SDK.
• Schematy jako kod - Mermaid/PlantUML/Graphviz/C4.

3) Styl i standardy

Przewodnik po jednym stylu (ton, terminologia, szablony tytułów, przykłady).
Słownik z terminami kanonicznymi (EN/RU), aliasy, zabronione preparaty.
Numeracja i odniesienia: stałe kotwy, odniesienia krzyżowe między ADR/RFC/kod.

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

4) Montaż i publikacja

• MkDocs (Materiał) - prosta, wygodna, dobra nawigacja i wyszukiwanie.
• Docusaurus - wersja dokumentacji i docs + blog; Komponenty MDX.
• Antora - dokumentacja modułowa dla dużych platform.

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) Schematy i diagramy jako kod

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ą renderowane na stronie; SDK/klienci/przykłady są generowane z nich.

6) Jakość: lintery i badania dokumentacji

• markdownlint - zasady formatowania Markdown.
• Vale - styl/terminologia/ton.
• Pisownia - pisownia (słowniki RU/EN).
• Linkcheck - linki zewnętrzne/wewnętrzne, kotwice.
• Doctest/Examples - wykonanie kodu snippets, synchronizacja wersji CLI/API.
• Schematest - walidacja 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 prowadzi 'python -m doktor docs/snippets/calc. py '.

7) Procesy: RFC/ADR/Recenzje i SLA dla przestarzałości

Przepływ RFC: inicjator → projekt kopii → dyskusja → decyzja → plan → wdrożenie → retro post facto.
Przepływ ADR: krótko naprawić wybór + odniesienie do RFC/eksperymenty.
Procedury przeglądu: źródło - "CODEOWNERS" + "doc-owners. yaml'.
SLA dla przestarzałości: artykuły krytyczne mają „last _ review” i alert do przeglądu w N dni.

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) Lokalizacja (i18n) i wielojęzyczność

Strategia lokalizacji: język źródłowy (EN lub RU) → tłumaczenie według gałęzi 'i18n/< locale>'.
Klucze i kontekst: przechowywać „stabilny identyfikator” dla nagłówków/fragmentów.
Kontrole: krok „brakujące klucze”, wpisy do desynchronizacji.
Style locale: lokalne glosariusze, nieprawidłowy papier śledzenia, przykłady kodu w lokalnym języku interfejsu użytkownika.

9) Integracja produktów

Wbudowana pomoc (docs in-app): komponenty MDX, wskazówki kontekstowe.
Wersioning przez zwolnienie: tagi/branches 'docs/vX. Y ', strona z wersjami selektorowymi.
Automatyczna generacja sekcji: z OpenAPI/AsyncAPI, GraphQL SDL, CLI '--help'.
Changelog jako kod: automatyczna generacja przez etykiety PR (feat/fix/docs/breaking).

10) Metryka i obserwowalność dokumentacji

Docs SLO: budować/publikować czas, uptime witryny, czas wygląd dokumentu po PR.
Zakres artefaktu: udział usług z ADR, udział punktów końcowych z przykładami, udział Runbooków z „kontrolami zdrowotnymi”.
Wskaźniki użytkownika: wyszukiwanie bez odpowiedzi, głębokość oglądania, CTR wbudowanych wierszy.
Jakość: błędy lintera/1000 linii, „złamane linki”, odsetek przestarzałych artykułów.

11) Bezpieczeństwo i prywatność

Tajemnice i PD są zabronione w repo; Linters do sekretów i maskowania.
dostęp do strony wewnętrznej za pośrednictwem SSO; sekcje publiczne oddzielone.
Zasady eksportu: PDF/archiwum bez linków wewnętrznych, znaki wodne dla dokumentów poufnych.
Sanitarne zrzuty ekranu: automatyczna anonimizacja (mok data/blur).

12) Wzory

Dokumentacja w PR. Każda zmiana wpływająca na zachowanie polega na aktualizacji doków w tym samym PR.
Szablony jako umowa. Tworzenie serwisu/punktu końcowego/zbioru danych - poprzez generator, który umieszcza puste doki.
Wykresy jako kod. Dowolny obraz - edytowalne źródło, zespół SVG/PNG w CI.
Podgląd dokumentacji. Bot komentarz z linkiem do podglądu strony dla PR.
Łącza dokujące w kodzie. Adnotacje w źródłach ('@ doc: adr/0007'), które są wyświetlane na stronie.

13) Anty-wzory

Dokumentacja w wiki/Pojęcie bez wersji obok kodu → z synchronizacji.
Zrzuty ekranu bez źródeł → niemożność automatycznej aktualizacji.
„Tajna” wiedza z czatów ustnych i prywatnych plików.
Generyki bez przykładów i niezmienne → bezużyteczne strony.
Brak właścicieli i „last _ review” → lawina przestarzałości.
Ręczne montaż i publikacja → kruche i rzadkie uwalnianie doków.

14) Przykłady automatyzacji

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 kontrolna architekta

1. Czy obok kodu znajduje się jedno repozytorium doków i wyraźna struktura?
2. Szablony (RFC/ADR/Runbook/How-To) i glosariusz opisane?
3. Linters included (markdownlint, Vale), spellcheck, linkcheck i doctest?
4. Schematy i diagramy - jak kod, montaż w CI?
5. Czy specyfikacje API (OpenAPI/AsyncAPI/Proto) są zatwierdzane i renderowane na stronę?
6. Zorganizowane docs-preview dla PR i auto-publish przez połączenie?
7. Czy są starzejące się SLA (last_review) i „właściciele” stron?
8. Metryka: zasięg, błędy lintera, złamane linki, wyszukiwanie „zero” zapytań?
9. Polityka bezpieczeństwa: tajemnice zakazane, SSO, znaki wodne/eksport?
10. Lokalizacja jest kontrolowana przez oddziały i sprawdzana pod kątem pominięć?

Wniosek

Docs-as-Code przekształca dokumentację z „notatek post-fact” w roboczy artefakt rozwoju: zmieniony, przetestowany i dostarczony. Dzięki temu podejściu wiedza żyje obok kodu, zmiany są przejrzyste, a użytkownicy i inżynierowie otrzymują aktualne instrukcje, schematy i przykłady, gdy są potrzebne. Zmniejsza to ryzyko operacyjne, przyspiesza wejście na pokład i poprawia jakość rozwiązań na całej platformie.