Internal documentation
Internal documentation should preserve what is hard to find in code, generated API docs, or Slack history:
- product invariants,
- domain models and their exceptions,
- historical decisions,
- operational runbooks,
- edge cases and the reasons why the system behaves in non-obvious ways.
What belongs here
Section titled “What belongs here”| Type | Example |
|---|---|
| Architecture overview | Application surfaces, Rails layers, background jobs, async flows. |
| Domain invariants | Why a participation exists, how versions change, what cannot be deleted. |
| Operational runbooks | What to inspect when assignments, imports, or webhooks look wrong. |
| Historical context | Why a behavior exists even when it looks surprising in the UI. |
First migration candidates
Section titled “First migration candidates”| Source | Note |
|---|---|
knowspread/docs/content_assigner.md | Already strong domain documentation. |
knowspread/docs/digital-ocean.md | Operational knowledge and historical notes. |
knowspread/swagger/rest/v1/swagger.yaml | Source for API documentation. |
knowspread/docs/model/*.plantuml | Older diagrams suitable for Mermaid migration or preservation as reference. |