tomevault-io Memex Documentation Guidelines
Follow these rules when writing or editing documentation in this project.
Core Principles
- Update existing content first - Never add new sections when existing ones cover the same topic
- Token efficiency - Every token costs context budget
- Section-level loading - The context-enricher loads specific sections via anchors
- Single source of truth - Document once, reference everywhere
Size Limits
| Level | Max Lines | Target |
|---|---|---|
| File | 800 | 400-600 |
| Section | 150 | 50-100 |
| Glossary/Index | 1000 | 500-800 |
If a file exceeds 800 lines, split into sub-documents:
DATABASE.md (overview + links)
DATABASE_SCHEMA.md
DATABASE_QUERIES.md
DATABASE_MIGRATIONS.md
Required Updates
When adding or changing features, update in this order:
- GLOSSARY.md - Add keywords for discoverability
- Specialized doc - Add/update detailed content
- CLAUDE.md - Only if it affects key files or constraints
Writing Style
Use Tables Over Paragraphs
# Instead of:
The pool uses minimum 5 connections, maximum 20, timeout 30 seconds.
# Use:
| Setting | Value |
|---------|-------|
| Min connections | 5 |
| Max connections | 20 |
| Timeout | 30s |
Use Anchor Links
# Instead of:
See DATABASE.md for query patterns.
# Use:
See [Query Patterns](DATABASE.md#queries).
Keep Code Examples Minimal
Show only relevant parts. Include just enough context to be useful.
Section Headers
Headers create anchor links for section-level loading:
## Main Section -> #main-section
### Subsection -> #subsection
Use descriptive headers that make good anchor names.
GLOSSARY.md Format
### Category Name
- **keyword** -> `path/to/FILE.md#section` - Brief description
- **another-keyword** -> `path/to/FILE.md` - Brief description
Update vs Add Decision
| Scenario | Action |
|---|---|
| Feature enhancement | Update existing section |
| Bug fix with behavior change | Update existing documentation |
| API parameter added | Update existing endpoint docs |
| Net-new feature | Create new section |
| Net-new component | Create new file |
Signs you should update instead of add:
- Existing section covers the same component
- Adding would duplicate context
- Old section would become misleading
When updating, fully replace outdated content. Don't append "UPDATE:" notes. Documentation should read as current truth.
Pre-Commit Checklist
- GLOSSARY.md updated with new keywords
- No section exceeds 150 lines
- No file exceeds 800 lines
- Anchor links used for cross-references
- Tables used for reference data
Converted and distributed by TomeVault — claim your Tome and manage your conversions.