Skip to content

INTERNAL_ORGANIZATION_STANDARD.md

Latest commit

 

History

History
153 lines (127 loc) · 5.74 KB

INTERNAL_ORGANIZATION_STANDARD.md

File metadata and controls

153 lines (127 loc) · 5.74 KB

📁 Internal Folder Organization Standard

This document defines the consistent internal structure for each main topic folder.

🎯 Goals

  • Separate learning from doing: Clear distinction between theory and practice
  • Consistent structure: Same organization across all topics
  • Easy navigation: Students know exactly where to find what they need
  • Professional appearance: Clean, organized structure

📂 Standard Internal Structure

Each main topic folder (like 6-Grouping-and-Aggregation/) should contain:

6-Grouping-and-Aggregation/
├── README.md                     # Main topic overview and navigation
│
├── 📁 concepts/                  # Learning materials (theory)
│   ├── group-by-basics.md       # Core concept explanations
│   ├── having-clause.md         # Detailed theory and rules
│   ├── advanced-grouping.md     # Complex concepts
│   └── visual-examples.md       # Diagrams and visual aids
│
├── 📁 examples/                  # SQL code demonstrations
│   ├── 01-group-by-examples.sql      # Working code examples
│   ├── 02-having-clause-examples.sql # Practical demonstrations
│   ├── 03-advanced-grouping.sql      # Complex examples
│   └── sample-data.sql              # Test data for examples
│
├── 📁 exercises/                 # Practice problems
│   ├── README.md                # Exercise instructions
│   ├── beginner-exercises.sql   # Easy practice problems
│   ├── intermediate-exercises.sql # Medium difficulty
│   ├── advanced-exercises.sql   # Challenging problems
│   └── solutions.sql           # All exercise solutions
│
└── 📁 resources/                # Optional: Additional materials
    ├── cheat-sheet.md          # Quick reference
    ├── common-mistakes.md      # Things to avoid
    └── performance-tips.md     # Optimization advice

🔍 File Purpose Guide

📖 /concepts/ - For Learning Theory

When to use: When you want to understand the concept

  • Explanations of how things work
  • Rules and syntax guidelines
  • When to use different approaches
  • Best practices and conventions

💻 /examples/ - For Seeing Implementation

When to use: When you want to see working code

  • Runnable SQL examples
  • Step-by-step demonstrations
  • Real-world use cases
  • Code you can copy and modify

🏋️ /exercises/ - For Practicing Skills

When to use: When you want to test your knowledge

  • Hands-on practice problems
  • Progressive difficulty levels
  • Self-assessment opportunities
  • Solutions for checking your work

📚 /resources/ - For Quick Reference

When to use: When you need quick answers

  • Cheat sheets and summaries
  • Common troubleshooting
  • Performance optimization tips

📝 Naming Conventions

Folders

  • Always lowercase: concepts/, examples/, exercises/
  • Descriptive and consistent across topics

Files

  • Markdown files: lowercase with hyphens: group-by-basics.md
  • SQL files: numbered for sequence: 01-basic-examples.sql
  • README files: always README.md

🎯 Learning Flow

Students should follow this path:

  1. Start: Read main README.md for topic overview
  2. Learn: Study files in /concepts/ folder
  3. See: Run examples from /examples/ folder
  4. Practice: Complete exercises in /exercises/ folder
  5. Reference: Use /resources/ for quick lookup

🏗️ Implementation Example

Let's reorganize 6-Grouping-and-Aggregation/ as an example:

Current (Mixed)

6-Grouping-and-Aggregation/
├── 01_group_by.sql           ❌ Mixed code and docs
├── 02_having_clause.sql      ❌ Mixed code and docs  
├── Advanced_Grouping.md      ❌ Mixed code and docs
├── GROUP_BY.md               ❌ Mixed code and docs
└── HAVING_Clause.md          ❌ Mixed code and docs

Improved (Organized)

6-Grouping-and-Aggregation/
├── README.md                 ✅ Clear topic overview
├── concepts/
│   ├── group-by-basics.md    ✅ Theory separated
│   ├── having-clause.md      ✅ Theory separated
│   └── advanced-grouping.md  ✅ Theory separated
├── examples/
│   ├── 01-group-by-examples.sql     ✅ Code separated
│   ├── 02-having-examples.sql       ✅ Code separated
│   └── 03-advanced-examples.sql     ✅ Code separated
└── exercises/
    ├── README.md             ✅ Practice problems
    ├── practice-problems.sql ✅ Practice problems
    └── solutions.sql         ✅ Practice problems

📊 Benefits of This Structure

For Students

  • ✅ Clear learning path: Know exactly what to do next
  • ✅ Find things quickly: Predictable organization
  • ✅ Separate concerns: Theory vs practice vs exercises
  • ✅ Progressive learning: Build skills step by step

For Contributors

  • ✅ Easy to add content: Know exactly where new material goes
  • ✅ Consistent maintenance: Same structure everywhere
  • ✅ Clear purpose: Each file has a specific role
  • ✅ Scalable organization: Works for any topic complexity

For the Project

  • ✅ Professional appearance: Looks organized and mature
  • ✅ Better discoverability: Content is easier to find
  • ✅ Improved navigation: Clear relationships between materials
  • ✅ Future-proof: Structure accommodates growth

🚀 Next Steps

  1. Choose pilot folder to reorganize first
  2. Create subfolder structure within existing topic
  3. Move and rename files to match new organization
  4. Update README files with new navigation
  5. Test the learning flow with reorganized content
  6. Apply to all remaining folders systematically