metabuilder/docs/DOCS_ORGANIZATION_GUIDE.md

📚 MetaBuilder Documentation Organization Guide

Welcome! All MetaBuilder documentation is organized in the /docs folder. This guide helps you navigate it effectively.

TODO: This file is already in docs/; links that start with ./docs/ are broken and should be updated to correct relative paths.

🚀 Quick Start (Choose Your Path)

👤 I'm New to MetaBuilder

→ Start here: docs/getting-started/NEW_CONTRIBUTOR_PATH.md
A structured 2-3 hour learning path that teaches you everything you need to know.

🔍 I Need Something Specific

→ Use this: docs/NAVIGATION.md
Master navigation hub with links to all documentation organized by category.

📖 I Want to Browse

→ Go here: docs/INDEX.md
Quick navigation with highlighted quick-reference links.

🗂️ I Want to Understand the Structure

→ Read this: docs/ORGANIZATION.md
Detailed breakdown of how documentation is organized.

---

📂 Directory Structure

docs/
├── NAVIGATION.md              ← 🗺️ Master navigation (use this!)
├── INDEX.md                   ← Quick nav hub
├── ORGANIZATION.md            ← How docs are organized
├── README.md                  ← Docs overview
│
├── getting-started/
│   ├── NEW_CONTRIBUTOR_PATH.md   ← 👈 NEW TEAM MEMBERS START HERE
│   ├── README.md
│   ├── PRD.md
│   └── ...
│
├── architecture/              ← System design & concepts
├── testing/                   ← Testing guidelines & patterns
├── implementation/            ← How-to guides for features
├── refactoring/               ← Code quality standards
├── packages/                  ← Package system docs
├── guides/                    ← How-to guides & tutorials
├── dbal/                      ← Database abstraction layer
├── api/                       ← API reference
├── deployments/               ← Deployment & DevOps
├── development/               ← Development workflows
├── database/                  ← Database documentation
├── quality-metrics/           ← Code quality & metrics
├── security/                  ← Security best practices
├── lua/                       ← Lua scripting
├── troubleshooting/           ← Problem solving
├── reference/                 ← Quick reference & lookup
├── archive/                   ← Historical/deprecated docs
├── stub-detection/            ← Stub detection system
├── src/                       ← Source code documentation
├── migrations/                ← Database migrations
├── iterations/                ← Project iteration histories
└── builds/                    ← Build system docs

---

🎯 Common Tasks

I want to...	Link	Time
Get started developing	NEW_CONTRIBUTOR_PATH.md	2-3 hrs
Understand the architecture	5-level-system.md	15 min
Write a test	TESTING_GUIDELINES.md	10 min
Create a new component	implementation/COMPONENT_MAP.md	20 min
Add a database feature	DBAL_INTEGRATION.md	30 min
Deploy the application	deployments/README.md	15 min
Fix a bug	refactoring/REFACTORING_STRATEGY.md	varies
Create a package	packages/README.md	30 min
Solve a problem	troubleshooting/README.md	varies
Run tests locally	guides/ACT_CHEAT_SHEET.md	5 min

---

📊 Documentation Quick Facts

• Total Files: 144+ markdown documents
• Main Categories: 23 directories
• Quick References: 10+ cheat sheets & quick-start guides
• Implementation Guides: 15+ detailed step-by-step guides
• Architecture Documentation: 8+ core architecture files

---

🔑 Key Documentation

MUST READ (Everyone)

1. 5-level-system.md - Permission hierarchy
2. TESTING_GUIDELINES.md - How we test
3. Copilot Instructions - Development standards

MUST READ (By Role)

Frontend Developers:

• generic-page-system.md - Component rendering
• packages/README.md - Package system
• guides/SASS_CONFIGURATION.md - Styling

Backend Developers:

• DBAL_INTEGRATION.md - Database layer
• database/PRISMA_SETUP.md - ORM setup
• migrations/README.md - Migrations

DevOps/Infrastructure:

• deployments/README.md - Deployment
• deployments/GITHUB_WORKFLOWS_AUDIT.md - CI/CD
• builds/CROSS_PLATFORM_BUILD.md - Builds

QA/Testing:

• TESTING_GUIDELINES.md - Test standards
• testing/TESTING_IMPLEMENTATION_SUMMARY.md - Implementation
• testing/FUNCTION_TEST_COVERAGE.md - Coverage

---

🔍 Search Tips

Using VS Code

1. Quick Open: Ctrl+P (or Cmd+P on Mac)
2. Search Examples:
   • testing - Find testing files
   • DBAL - Find DBAL documentation
   • refactoring - Find refactoring guides
   • arch/ - Browse architecture files

Using File Search

• Ctrl+Shift+F (or Cmd+Shift+F on Mac) to search within files
• Search for "ERROR:", "TODO:", "FIXME:" to find action items

---

📝 Navigation Patterns

From Root

Files at the root level are kept minimal:

• README.md - Project overview
• CONTRIBUTING.md - Contribution guidelines
• START_HERE.md - Entry point
• All other docs are in /docs folder ✅

By Category

Browse /docs/{category}/README.md for category overview:

• docs/architecture/README.md - Architecture overview
• docs/testing/README.md - Testing overview
• docs/implementation/README.md - Implementation overview

Quick References

Most categories have quick-reference guides:

• QUICK_START.md - Fast onboarding
• CHEAT_SHEET.md - Quick lookup
• QUICK_REFERENCE.md - Common patterns

---

💡 Pro Tips

✅ DO:

• ✅ Start with NEW_CONTRIBUTOR_PATH.md if you're new
• ✅ Use NAVIGATION.md to find anything
• ✅ Check troubleshooting/ if stuck
• ✅ Reference archive/ for historical context
• ✅ Keep Copilot Instructions handy

❌ DON'T:

• ❌ Search randomly - use the navigation files
• ❌ Refer to archived docs for current practices
• ❌ Ignore the 5-level-system.md - it's critical
• ❌ Skip the TESTING_GUIDELINES.md
• ❌ Add docs to root - everything goes in /docs folder

---

🤝 Contributing

When you add new documentation:

1. Save it in the right place - Use the category structure
2. Update the README.md in that category
3. Update NAVIGATION.md - Add a link
4. Add a brief description - Help others find it
5. Use consistent formatting - Follow existing doc style

For guidelines, see ORGANIZATION.md.

---

🆘 Still Lost?

Try these in order:

1. NAVIGATION.md - Find by category
2. NEW_CONTRIBUTOR_PATH.md - Structured learning
3. troubleshooting/ - Common issues
4. INDEX.md - Quick nav hub
5. Copilot Instructions - Ask for help

---

📚 Full Documentation Tree

See the complete documentation tree in NAVIGATION.md.

---

Last Updated: December 2025
Next Task: Go to docs/getting-started/NEW_CONTRIBUTOR_PATH.md to start learning! 🚀