How to Organize Documentation

Simple guide for organizing and writing documentation in the GoGrab Space monorepo

📚 How to Organize Documentation

Simple, practical guide for organizing and writing documentation in the GoGrab Space monorepo

🎯 Quick Start

Before Writing Anything:

✅ Check current session ID: cat docs/sessionID.json
✅ Check active docs root: cat apps/docs-angular/docs-config.ts
✅ Decide where it belongs: Use the decision tree below

📂 Where Does My Documentation Belong?

Decision Tree

Is it specific to a project/app?
├── YES → docs/english/<ProjectName>/
│   ├── GoGrab-Space/ (main platform)
│   ├── Backend-Api/ (backend)
│   ├── Docs-angular/ (documentation system)
│   └── etc.
│
└── NO → Is it general development info?
    ├── YES → docs/english/public/development/
    ├── Is it troubleshooting?
    │   └── YES → docs/english/public/troubleshooting/
    ├── Is it AI agent instructions?
    │   └── YES → docs/english/Ai-instructions/
    └── Not sure?
        └── docs/english/public/miscellaneous/

🗂️ Folder Organization Rules

1. Use Logical Subdirectories

❌ BAD - Everything at root level:

my-project/
├── feature-1.md
├── feature-2.md
├── bug-fix-1.md
├── implementation-1.md
└── 20+ more files...

✅ GOOD - Organized by topic:

my-project/
├── index.mdc                    # Main navigation
├── README.md                    # Quick overview
├── features/                    # Feature documentation
│   ├── feature-1.md
│   └── feature-2.md
├── troubleshooting/             # Problem solving
│   └── bug-fix-1.md
├── implementation/              # Implementation guides
│   └── implementation-1.md
└── progress-notes/              # Session notes
    └── SESSION_1_NOTES.md

2. Folder Naming Conventions

✅ Use kebab-case: my-feature-docs/
✅ Be descriptive: sync-architecture/ not stuff/
✅ No numbers: core-architecture/ not 01-core-architecture/
✅ Group by topic: Not by date or author

3. Common Folder Structure

Every major project should have:

project-name/
├── index.mdc                    # Main navigation & overview
├── README.md                    # Quick start (optional)
│
├── features/                    # Feature documentation
├── architecture/                # Architecture docs
├── implementation-plans/        # Roadmaps & plans
├── troubleshooting/             # Problem solving
├── api-reference/               # API docs (if applicable)
│
└── progress-notes/              # Session-by-session notes
    ├── SESSION_1_PLANNING.md
    ├── SESSION_2_IMPLEMENTATION.md
    └── session-3-completion.md  # Final notes use kebab-case

📝 File Naming Rules

General Files

✅ Use kebab-case: my-feature-guide.md
✅ Be descriptive: mongodb-sync-fix.md not fix.md
✅ No dates in name: Use frontmatter instead

Progress Notes

✅ ALL CAPS + UNDERSCORES: SESSION_1_PLANNING.md
✅ Clear purpose: PHASE_2_IMPLEMENTATION.md
✅ Final notes: Use kebab-case when project is complete

Why? Makes it obvious which files are in-progress session notes vs. polished documentation.

Index Files

✅ Always .mdc: index.mdc (not index.md)
✅ One per folder: Main navigation for that section
✅ Include frontmatter: Title, description, icon

README Files

✅ Always .md: README.md (not README.mdc)
✅ Quick overview: Brief description of folder contents
✅ Optional: Only if index.mdc needs a companion

📋 Frontmatter Template

Every documentation file must have frontmatter:

---
title: My Feature Guide
description: Brief description for search and navigation
icon: 📚                           # Emoji that represents the content
created: November 18, 2025 - 11:35 AM
updated: November 18, 2025 - 11:35 AM
sessionID: 11.25.1.1               # REQUIRED! Check docs/sessionID.json
status: ✅ Complete                # ✅ Complete, 🔄 In Progress, 📋 Planned
purpose: Why this document exists
order: 1                           # Display order in navigation (optional)
---

Frontmatter Fields

Field	Required	Description
`title`	✅ Yes	Document title
`description`	✅ Yes	Brief description for search
`icon`	✅ Yes	Emoji representing content
`created`	✅ Yes	Full date and time created
`updated`	⚠️ When modified	Last update date/time
`sessionID`	✅ Yes	Check `docs/sessionID.json`
`status`	✅ Yes	✅ Complete, 🔄 In Progress, 📋 Planned
`purpose`	✅ Yes	Why this document exists
`order`	⚪ Optional	Display order in navigation
`tags`	⚪ Optional	Search tags

🎨 Content Guidelines

1. Headers

✅ Keep simple: ## Section Title
❌ Avoid fancy: ## 🧩 **SECTION TITLE**

Why? Complex headers break anchor links.

2. Links

✅ Absolute paths: /section/page
✅ No extensions: Don't include .md
✅ No language prefix: System adds /es automatically
❌ No /public/ or /english/: Paths are relative to docs root

Examples:

✅ [Feature Guide](/GoGrab-Space/features/my-feature)
✅ [Troubleshooting](/troubleshooting/sync-errors)
❌ [Bad Link](/english/public/troubleshooting/sync-errors.md)

3. Code Blocks

✅ Specify language: ```typescript, ```bash, etc.
✅ Add comments: Explain what code does
✅ Keep concise: Show only relevant parts

4. Visual Aids

✅ Use diagrams: Mermaid for flowcharts
✅ Use tables: For comparisons
✅ Use emoji: For visual markers (sparingly)

🔄 Workflow

Creating New Documentation

# 1. Check current session ID
cat docs/sessionID.json

# 2. Determine location using decision tree
# (See "Where Does My Documentation Belong?" above)

# 3. Create file with proper frontmatter
# Use the template above

# 4. Write content following guidelines

# 5. Update parent index.mdc to link to new doc

# 6. Scan documentation system
yarn docs:scan

Updating Existing Documentation

# 1. Edit the file

# 2. Update frontmatter:
#    - Change 'updated' date/time
#    - Update 'status' if needed

# 3. If structure changed, update index.mdc

# 4. Scan documentation system
yarn docs:scan

📁 Real-World Example

Let's say you're documenting a new sync feature:

1. Determine Location

✅ Project-specific? Yes → GoGrab-Space
✅ Architecture? Yes → architecture/
✅ Sync-related? Yes → sync-architecture/

Path: docs/english/GoGrab-Space/architecture/sync-architecture/

2. Create File

Filename: real-time-sync-implementation.md

3. Add Frontmatter

---
title: Real-Time Sync Implementation
description: How we implemented real-time cross-browser synchronization
icon: 🔄
created: November 18, 2025 - 11:45 AM
sessionID: 11.25.1.1
status: ✅ Complete
purpose: Document real-time sync architecture for future reference
order: 5
---

4. Write Content

Use clear headers, code examples, diagrams.

5. Update index.mdc

Add link in docs/english/GoGrab-Space/architecture/index.mdc:

#### **2.2 Improvements & Fixes**
- **[Real-Time Sync Implementation](./sync-architecture/real-time-sync-implementation.md)** - Real-time sync

6. Scan

yarn docs:scan

🎯 Special Cases

Progress Notes

Location: <project>/progress-notes/

Naming: SESSION_X_DESCRIPTION.md (ALL CAPS)

When to use:

Session-by-session development notes
Work-in-progress documentation
Quick capture of decisions/changes

When to convert to final docs:

Project/phase is complete
Documentation is polished
Ready for long-term reference

API Reference

Location: <project>/api-reference/

Structure:

api-reference/
├── index.mdc              # Overview
├── endpoints/             # Individual endpoints
├── schemas/               # Data schemas
└── examples/              # Usage examples

Troubleshooting

Location: <project>/troubleshooting/ or docs/english/public/troubleshooting/

Naming: PROBLEM-DESCRIPTION.md (e.g., 500-UNIVERSE-UPDATE-ERROR.md)

Template:

# Problem Title

## Symptom
What error/issue occurs

## Root Cause
Why it happens

## Solution
How to fix it

## Prevention
How to avoid in future

Architecture Decisions

Location: <project>/architecture/

Consider using:

core-architecture/ - System design
implementation-plans/ - Roadmaps
analysis-audits/ - Reviews

✅ Checklist

Before finalizing documentation:

✅ Checked docs/sessionID.json for current session
✅ File in correct location per decision tree
✅ Frontmatter complete (title, description, icon, dates, sessionID)
✅ Headers are simple and clean
✅ Links use absolute paths without extensions
✅ Code blocks have language specified
✅ Parent index.mdc updated with link
✅ Ran yarn docs:scan
✅ Progress notes use ALL_CAPS_NAMING
✅ Final docs use kebab-case naming

🚫 Common Mistakes to Avoid

❌ Wrong:

docs/english/public/my-feature.md              # No organization
docs/english/GoGrab-Space/01-feature/          # Numbers in folder names
docs/english/GoGrab-Space/2025-11-18-fix.md   # Dates in filenames
[Link](/english/public/section/page.md)       # Wrong path format
## 🎯 **MY SECTION**                           # Fancy headers

✅ Right:

docs/english/GoGrab-Space/features/my-feature.md
docs/english/GoGrab-Space/architecture/sync-architecture/
docs/english/GoGrab-Space/troubleshooting/mongodb-fix.md
[Link](/GoGrab-Space/features/my-feature)
## My Section

📚 Related Documentation

AGENTS.md - AI agent documentation guide
Session ID System - Session tracking
Architecture Index - Example of good organization

💡 Tips for Success

Start with structure - Create folders before writing
Use templates - Copy frontmatter from existing docs
Think about search - Use descriptive titles and descriptions
Link everything - Make docs interconnected
Keep it simple - Clear > Clever
Update regularly - Documentation is never "done"
Scan after changes - yarn docs:scan updates navigation

🎓 Philosophy

Good documentation is:

✅ Easy to find - Logical organization
✅ Easy to read - Clear structure
✅ Easy to maintain - Consistent patterns
✅ Easy to navigate - Good linking
✅ Easy to search - Descriptive metadata

Remember: Documentation is for humans. Make it human-friendly!

Last Updated: November 18, 2025 - 11:35 AM
Session: 11.25.1.1
Maintainer: Documentation Team

Questions? Check AGENTS.md or ask the team! 🚀