Практики документирования

Documentation — часто neglected, но foundation для team scalability и knowledge preservation.

Levels

API docs: OpenAPI, auto-generated. Code comments: for "why", not "what". README: getting started. Architecture Decision Records (ADR): key decisions с context. Runbooks: operational procedures. Onboarding docs: new hire path. Different audiences, different formats.

Docs as code

Markdown в repo. Version-controlled. Reviewed через PR. Auto-generated where possible. CI validation (link checking). Deployed as static site (Docusaurus, MkDocs, GitBook). Search critical. Templates для consistency.

ADR

Architecture Decision Records: numbered docs recording key decisions. Structure: Context, Decision, Consequences. Immutable: superseded не удаляется. Cheap insurance для future engineers. Prevent same debates повторно.

Gaming specifics

Game design docs (GDD): comprehensive. Math specifications: certification requires. Compliance docs: regulator visibility. Third-party integration docs: game providers, PSPs. Retention 5–10 years для licensed operators. Documentation debt = compliance risk.