documentation-standards

To structure project documentation, use a layered hierarchy with concise README front pages, dedicated docs directories, and ADRs. Enforce relative links and clear audience separation to maintain consistency across single-package or multi-module repositories.

Writing a concise README involves keeping front pages short, layering detailed information into a docs directory, and using relative links. Following a style-guide ensures the README remains maintainable and clearly separates audiences.

Use Architecture Decision Records (ADRs) in your docs directory to log important technical choices and their rationales. ADRs enforce documentation standards by providing a consistent, maintainable history of architectural changes for project audiences.

Yes, these documentation standards apply to both single-package projects and multi-module repositories. The guidelines scale by defining specific documentation hierarchies, ensuring concise READMEs and appropriate docs directory layering regardless of project size.

Review existing project docs by checking for concise front pages, layered documentation structures, and proper ADR conventions. Rewriting bloated content into a clean README and docs layout enforces consistency and removes verbosity.

Agent instruction files like AGENTS.md or CLAUDE.md belong at the root level and contain specific guidance for automated agents. They are part of a standard documentation hierarchy that separates human-readable READMEs from machine-focused instructions.