Source synchronization
A separate repository reduces the risk that documentation interferes with production code. It also increases drift risk. Every imported artifact must therefore be traceable.
- Automatically imported files should not be edited manually.
- Pages derived from code should state the source commit.
- Generated API reference should be separate from hand-written guides.
- If documentation and product behavior differ, open a feedback item or issue.
Sync candidates
Section titled “Sync candidates”| Artifact | Source |
|---|---|
| OpenAPI | knowspread/swagger/rest/v1/swagger.yaml |
| DB schema diagram | knowspread/docs/schema.html |
| Existing technical docs | knowspread/docs/*.md |
| PlantUML diagrams | knowspread/docs/model/*.plantuml |
Recommended modes
Section titled “Recommended modes”| Mode | Use |
|---|---|
| Manual migration | Text needs interpretation and product decision. |
| Generated artifact | OpenAPI, schema diagram, endpoint export. |
| AI draft | First page proposal from sources, always with human review. |
| Drift check | Verify that a document still matches code or OpenAPI. |