Files
reverse-engineering-anything/docs/development/documentation.md
T

3.6 KiB

Documentation ownership and authoring

Use the documentation directory to find existing material before adding another guide. Preserve one canonical owner for each contract or workflow; link to that owner instead of copying its claims into several guides.

When a contract changes, update its owning page with the implementation. Check the examples and recovery steps in related guides against the supported CLI and MCP entry points. Link guides to the section that owns the shared behavior so readers can reach it from the task they are performing.

Choose a destination

Document Destination
Installation, client setup and first CLI/MCP steps docs/getting-started/
Analyst workflows and evidence interpretation docs/guides/<domain>/
Analysis-engine configuration and format prerequisites docs/providers/
Shared runtime contracts and evidence semantics docs/reference/
Development, testing, release and authoring instructions docs/development/
Compatibility changes for a released version docs/migrations/

Use meaningful, lowercase slugs. Guides describe current workflows, behavior and limitations. Ground their claims in the implementation and verify examples through the supported entry points.

Follow the repository guidance on where to keep planning and architecture records and the contribution scope for proposals that require a maintainer decision.

Use relative links to physical Markdown files so GitHub readers can follow them. Link repository files outside docs/ with their full GitHub URLs. Preserve existing heading anchors when moving a guide.

documentation.ts owns categorized site navigation and the existing guides' stable public routes. Update it and the documentation directory when adding or recategorizing a guide. VitePress rewrites categorized sources to the existing public paths; its Markdown hook resolves repository links from the physical source and renders them against those public routes. Keep basenames and route assignments unique. Edit links use the physical source file.

For a move, search for both the basename and its old full path. Update README translations, authored skills, verification instructions, documentation-fact readers and release configuration when they consume that path. Preserve historical release records and references bound to earlier commits or tags.

Generated ownership and checks

The documentation directory lists generated files, their producers, and release records. Scripts, package consumers, and release history depend on the listed paths. Update the producer or its inputs and regenerate.

Do not write the number of tools in living prose; link the generated catalog instead. docs:check refuses a count of ten or more tools outside dated records (docs/releases/ and docs/verification/).

Run npm run docs:check for documentation facts and generated consistency, and npm run verify:docs:routes to build the complete production site and check local links, anchors and physical edit targets. When a physical path moves, also run the tests that read it. Follow development checks before requesting review.