Updating Project Documentation
Documentation Structure
The project has a layered documentation structure. Understand it before making changes.
Root files
Standard GitHub-recognized files that stay at the project root:
| File |
Purpose |
Update when... |
README.md |
Project overview, "What You'll Find Here", links |
Features visible to users change, new top-level sections added |
CONTRIBUTING.md |
How to contribute content (digests, articles, resources) |
Contribution workflows or content guidelines change |
DEVELOPMENT.md |
Slim redirect to docs/dev/INDEX.md |
Almost never -- only if docs/dev/ moves |
User-facing documentation (docs/)
Project-specific docs aimed at non-developer users and contributors. Currently none exist; the convention is documented here for future use.
| Convention |
Rule |
| Location |
docs/ (not root, not docs/dev/) |
| Naming |
UPPERCASE with underscores (e.g., GETTING_STARTED.md) |
Developer documentation (docs/dev/)
| File |
Purpose |
Update when... |
INDEX.md |
Central index linking to all dev docs |
A new dev doc is added or an existing one is renamed/removed |
development.md |
Setup, project structure, mailing list, tech stack |
Dependencies, project structure, commands, or config change |
git-workflow.md |
Commit conventions, branches, PRs, publishing |
Git workflow conventions change |
design.md |
Website goals and roadmap |
Project goals or roadmap change |
technology.md |
Technology choices, architecture, phased roadmap |
Technology decisions or architecture change |
mailing-list-troubleshooting.md |
Common mailing list issues and solutions |
New mailing list issues are discovered or resolved |
Adding new documentation
User-facing doc (aimed at users/contributors):
- Create the file in
docs/ (UPPERCASE, underscores, .md)
- Add a link from
README.md or CONTRIBUTING.md where relevant
Developer doc (aimed at developers of the site):
- Create the file in
docs/dev/ (lowercase, hyphens, .md)
- Add an entry to the table in
docs/dev/INDEX.md
- If it replaces content from another doc, remove the old content and add a cross-reference
What to Update After a Feature
After implementing a feature or significant change, review this checklist:
- [ ] Does `README.md` still accurately describe the project and its sections?
- [ ] Does `CONTRIBUTING.md` still reflect the correct contribution process?
- [ ] Does `docs/dev/development.md` still match the project structure, commands, and config?
- [ ] If a new dev topic was introduced, does it need its own doc in `docs/dev/`?
- [ ] Are all cross-references between docs still valid (no broken links)?
- [ ] Do related skills in `.cursor/skills/` need updating?
Only update what actually changed -- don't rewrite docs unnecessarily.
Cross-Reference Rules
README.md and CONTRIBUTING.md link to docs/dev/INDEX.md for technical details (not directly to sub-docs)- User-facing docs in
docs/ are linked from README.md or CONTRIBUTING.md where relevant
- Docs within
docs/dev/ link to each other by relative path (e.g., [Git Workflow](git-workflow.md))
- Docs linking back to root files use
../../ (e.g., ../../README.md)
- Skills in
.cursor/skills/ reference docs via ../../../docs/dev/ or ../../../docs/ relative paths
Style Conventions
- Use sentence case for headings (capitalize first word only, plus proper nouns)
- Keep docs factual and concise -- no filler
- Use tables for structured reference, bullet lists for quick overviews
- Include code blocks with actual commands when documenting workflows
- Provide good/bad examples when documenting conventions
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: update-docs-143description: Update project documentation after feature development or code changes. Use when adding features, modifying functionality, changing project structure, updating configuration, or when any documentation needs to reflect recent changes. Use when this capability is needed.4---56# Updating Project Documentation78## Documentation Structure910The project has a layered documentation structure. Understand it before making changes.1112### Root files1314Standard GitHub-recognized files that stay at the project root:1516| File | Purpose | Update when... |17|------|---------|----------------|18| `README.md` | Project overview, "What You'll Find Here", links | Features visible to users change, new top-level sections added |19| `CONTRIBUTING.md` | How to contribute content (digests, articles, resources) | Contribution workflows or content guidelines change |20| `DEVELOPMENT.md` | Slim redirect to `docs/dev/INDEX.md` | Almost never -- only if docs/dev/ moves |2122### User-facing documentation (`docs/`)2324Project-specific docs aimed at non-developer users and contributors. Currently none exist; the convention is documented here for future use.2526| Convention | Rule |27|------------|------|28| Location | `docs/` (not root, not `docs/dev/`) |29| Naming | UPPERCASE with underscores (e.g., `GETTING_STARTED.md`) |3031### Developer documentation (`docs/dev/`)3233| File | Purpose | Update when... |34|------|---------|----------------|35| `INDEX.md` | Central index linking to all dev docs | A new dev doc is added or an existing one is renamed/removed |36| `development.md` | Setup, project structure, mailing list, tech stack | Dependencies, project structure, commands, or config change |37| `git-workflow.md` | Commit conventions, branches, PRs, publishing | Git workflow conventions change |38| `design.md` | Website goals and roadmap | Project goals or roadmap change |39| `technology.md` | Technology choices, architecture, phased roadmap | Technology decisions or architecture change |40| `mailing-list-troubleshooting.md` | Common mailing list issues and solutions | New mailing list issues are discovered or resolved |4142### Adding new documentation4344**User-facing doc** (aimed at users/contributors):45461. Create the file in `docs/` (UPPERCASE, underscores, `.md`)472. Add a link from `README.md` or `CONTRIBUTING.md` where relevant4849**Developer doc** (aimed at developers of the site):50511. Create the file in `docs/dev/` (lowercase, hyphens, `.md`)522. Add an entry to the table in `docs/dev/INDEX.md`533. If it replaces content from another doc, remove the old content and add a cross-reference5455## What to Update After a Feature5657After implementing a feature or significant change, review this checklist:5859```60- [ ] Does `README.md` still accurately describe the project and its sections?61- [ ] Does `CONTRIBUTING.md` still reflect the correct contribution process?62- [ ] Does `docs/dev/development.md` still match the project structure, commands, and config?63- [ ] If a new dev topic was introduced, does it need its own doc in `docs/dev/`?64- [ ] Are all cross-references between docs still valid (no broken links)?65- [ ] Do related skills in `.cursor/skills/` need updating?66```6768Only update what actually changed -- don't rewrite docs unnecessarily.6970## Cross-Reference Rules7172- `README.md` and `CONTRIBUTING.md` link to `docs/dev/INDEX.md` for technical details (not directly to sub-docs)73- User-facing docs in `docs/` are linked from `README.md` or `CONTRIBUTING.md` where relevant74- Docs within `docs/dev/` link to each other by relative path (e.g., `[Git Workflow](git-workflow.md)`)75- Docs linking back to root files use `../../` (e.g., `../../README.md`)76- Skills in `.cursor/skills/` reference docs via `../../../docs/dev/` or `../../../docs/` relative paths7778## Style Conventions7980- Use **sentence case** for headings (capitalize first word only, plus proper nouns)81- Keep docs factual and concise -- no filler82- Use tables for structured reference, bullet lists for quick overviews83- Include code blocks with actual commands when documenting workflows84- Provide good/bad examples when documenting conventions8586---87> Converted and distributed by [TomeVault](https://tomevault.io/claim/roo4l) — claim your Tome and manage your conversions.88<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io