Skip to content
HeliosDB HeliosDB Full

Documentation Organization Guidelines - Quick Summary

Documentation Organization Guidelines - Quick Summary

📋 Quick Reference

This is a condensed version of the documentation guidelines found in /CLAUDE.md. For complete details, always refer to the main CLAUDE.md file.

Golden Rule

Always consult DOCUMENTATION_INDEX.md before creating or moving any documentation file.

File Placement Quick Guide

Where Does My File Go?

If your file is a…Put it in…
Daily/weekly session reportdocs/reports/sessions/
Hive mind coordination reportdocs/reports/distributed execution/
Agent execution reportdocs/reports/agents/
Phase completion reportdocs/reports/phase/
Feature completion reportdocs/reports/completion/
Security audit/analysisdocs/analysis/security/
Performance benchmark analysisdocs/analysis/performance/
Codebase gap/consolidation analysisdocs/analysis/codebase/
Execution plan or roadmapdocs/planning/
Architecture or design docdocs/architecture/
Protocol specificationdocs/protocol/
Feature-specific documentationdocs/features/[feature-name]/
Getting started guidedocs/quick-starts/
API or reference documentationdocs/reference/
User guidedocs/guides/user/
Developer guidedocs/guides/developer/
Implementation reportdocs/implementation/
Test documentationdocs/testing/
HeliosDB Lite specificdocs/heliosdb-lite/
Benchmark scriptscripts/benchmarks/
Deployment scriptscripts/deployment/
Testing scriptscripts/testing/
Utility scriptscripts/utilities/

Naming Conventions

Document TypeNaming PatternExample
Session ReportSESSION_SUMMARY_[DATE].mdSESSION_SUMMARY_NOV14_2025.md
Daily ReportDAY[N]_*.mdDAY1_COMPLETION_REPORT.md
Weekly ReportWEEK[N]_*.mdWEEK1_PROGRESS_TRACKER.md
Phase ReportPHASE[N]_*.mdPHASE2_COMPLETE_REPORT.md
Feature Completion[FEATURE]_COMPLETION_REPORT.mdMVCC_COMPLETION_REPORT.md
Analysis[TOPIC]_ANALYSIS_REPORT.mdSECURITY_ANALYSIS_REPORT.md
Planning[SCOPE]_[TYPE]_PLAN.mdV5X_IMPLEMENTATION_PLAN.md

What Goes in Docs Root?

ONLY these files:

  • README.md - Main docs README
  • index.md - Docs index (if used)
  • Reorganization docs (temporary, during reorganization)

Everything else goes in subdirectories!

What Goes in Project Root?

ONLY these files:

  • Essential: README.md, CLAUDE.md, Cargo.toml, LICENSE
  • Indices: DOCUMENTATION_INDEX.md, QUICK_REFERENCE.md
  • Config: .gitignore, rust-toolchain, etc.

Never in root:

  • Data files, scripts, documentation (beyond indices), backups

Archive Guidelines

Archive (don’t delete) when files are:

  • Historical data no longer actively used
  • Superseded by newer versions
  • One-time scripts that completed their purpose
  • Research that informed completed implementation

Archive Locations:

  • benchmarks/results/archive/ - Historical benchmarks
  • docs/analysis/archive/ - Historical analysis
  • scripts/utilities/archive/ - Completed scripts
  • tests/archive/ - Test artifacts
  • docs/archive/2025-11/ - General historical docs

Every archive MUST have a README.md

Before Creating Any Documentation

Checklist:

  • Consulted DOCUMENTATION_INDEX.md for proper location
  • Checked for existing similar files (avoid duplicates)
  • Used correct naming convention
  • Placing in correct directory (not root!)
  • Will update indices if adding significant content

When to Update DOCUMENTATION_INDEX.md

Update when:

  • Adding new documentation category/subdirectory
  • Changing directory structure significantly
  • File counts change by 20%+ in any directory
  • Adding new major documentation sections
  • Completing major reorganization

What to Update:

  • File counts in Statistics section
  • Directory descriptions if changed
  • “Last Updated” date
  • Keep aligned with actual filesystem

Pre-Commit Verification

Before committing documentation:

  • File in correct directory per DOCUMENTATION_INDEX.md
  • Follows naming conventions
  • No duplicates created
  • Archive README updated (if archiving)
  • Relevant indices updated
  • No files in docs root (except allowed)
  • No misc files in project root
  • DOCUMENTATION_INDEX.md updated if needed

Common Mistakes to Avoid

❌ DON’T:

  • Place files in wrong directories
  • Create files in docs root (except README/index)
  • Leave backup files (.bak, .old)
  • Scatter related files across locations
  • Ignore DOCUMENTATION_INDEX.md structure
  • Delete historical files (archive instead)

DO:

  • Always check DOCUMENTATION_INDEX.md first
  • Use proper naming conventions
  • Keep structure organized
  • Archive (not delete) old files
  • Update indices when needed
  • Maintain professional organization

Quality Standards

All documentation must:

  • Be properly categorized by type/purpose
  • Use clear, descriptive filenames
  • Be in single most appropriate location
  • Include proper metadata (dates, purpose)
  • Match existing documentation style

Help & Resources

  • Full Guidelines: /CLAUDE.md (Documentation Organization section)
  • Complete Index: /DOCUMENTATION_INDEX.md
  • Quick Navigation: /QUICK_REFERENCE.md
  • Recent Reorganization: docs/REORGANIZATION_COMPLETE_NOV14_2025.md

Remember: Proper documentation organization is critical to project quality. Taking 30 seconds to check guidelines saves hours of reorganization later!

Last Updated: November 14, 2025