📚 Documentation & Best Practices Organizer

A powerful toolkit for organizing markdown documentation and extracting best practices from Git history. Creates multiple organizational facets with AI-friendly instructions for maintaining current best practices.

✨ Features

📄 Documentation Organization

• 🕒 Time-based Organization - Automatically sorts documents by modification date
• 🔄 SDLC Lifecycle Views - Organizes by development phases (planning, implementation, testing, etc.)
• ⚙️ System Function Categories - Groups by functional areas (admin tools, UI, integration, etc.)
• 📑 Comprehensive Index - Single index.md file with clickable links to all documentation
• 📅 Date Sorting - Files sorted by modification time (newest first) with timestamps
• 🔗 Symlink-based - Non-destructive organization preserving original file locations
• 🎨 VS Code Friendly - Optimized for VS Code explorer and markdown preview

🎯 Git-Based Best Practices Extraction

• 📊 Commit History Analysis - Analyzes Git patterns to identify successful practices
• 🤖 AI Integration Instructions - Generates guidelines for AI assistants to use latest practices
• 🚫 Deprecated Pattern Detection - Identifies and documents superseded approaches
• 📈 Evolution Timeline - Tracks how practices have evolved over time
• 🏷️ Categorical Organization - Groups practices by domain (architecture, development, etc.)
• 📅 Recency-based Views - Prioritizes recent discoveries vs established patterns

🚀 Quick Start

Documentation Organization

# Add to your project as submodule
git submodule add https://github.com/yourusername/docs-organizer.git tools/docs-organizer

# Organize documentation
cd tools/docs-organizer
./organize.sh /path/to/your/docs

Best Practices Extraction

# Extract practices from Git history (last 6 months)
./extract-practices.sh /path/to/your/project

# Custom analysis period and significance
./extract-practices.sh . -m 12 -s 4 --clean

# Outputs AI-friendly practice instructions

Standalone Usage

# Clone the repository
git clone https://github.com/yourusername/docs-organizer.git
cd docs-organizer

# Organize documentation
./organize.sh /path/to/your/markdown/docs

# Extract best practices from Git history
./extract-practices.sh /path/to/your/project

📁 Generated Structure

Documentation Organization

docs/
├── index.md                 # Comprehensive navigation index
├── README-NAVIGATION.md     # Usage guide
├── by-time/                 # Time-based organization
│   ├── today/
│   ├── yesterday/
│   ├── week-prior/
│   └── historical/
├── by-lifecycle/            # SDLC phase organization
│   ├── planning/
│   ├── implementation/
│   ├── testing/
│   ├── debugging/
│   ├── completion/
│   └── ...
└── by-system/               # System function organization
    ├── admin-tools/
    ├── ui-components/
    ├── integration/
    └── ...

Best Practices Structure

practices/
├── index.md                 # Master practices index with AI instructions
├── current-practices.md     # Active best practices
├── deprecated-practices.md  # Superseded approaches to avoid
├── evolution-timeline.md    # How practices evolved over time
├── by-category/            # Domain-specific practices
│   ├── architecture/
│   ├── development/
│   ├── testing/
│   ├── deployment/
│   └── ...
└── by-recency/             # Time-based practice organization
    ├── latest/             # Last 2 weeks
    ├── recent/             # Last 2 months
    └── established/        # Proven over time

🎯 Index Features

The generated index.md provides:

• 📅 Chronological listings with file timestamps
• 🔗 Clickable links to all documentation files
• 📊 Statistics dashboard showing document counts
• 🗂️ Multiple view facets for different navigation needs
• ⚡ Quick navigation menu with direct folder links

Example index entry:

- [PROJECT-SUCCESS-REPORT.md](../PROJECT-SUCCESS-REPORT.md) *(2025-06-15 08:25:38)*

⚙️ Configuration

Custom Classification

Edit the classification functions in organize.sh:

# Time-based classification
classify_by_time() {
    # Custom time bucket logic
}

# SDLC phase classification  
classify_by_lifecycle() {
    # Custom phase detection
}

# System function classification
classify_by_system() {
    # Custom function categorization
}

Directory Structure

Modify the base structure in create_base_structure():

# Add custom time periods
mkdir -p "$DOCS_ROOT/by-time/custom-period"

# Add custom SDLC phases
mkdir -p "$DOCS_ROOT/by-lifecycle/custom-phase"

# Add custom system categories
mkdir -p "$DOCS_ROOT/by-system/custom-category"

🔧 Usage Examples

Basic Organization

# Organize current directory
./organize.sh

# Organize specific directory
./organize.sh /path/to/docs

# Clean existing organization only
./organize.sh --clean

Integration with CI/CD

# GitHub Actions example
- name: Organize Documentation
  run: |
    git submodule update --init --recursive
    ./tools/docs-organizer/organize.sh docs/
    git add docs/
    git commit -m "Update documentation organization" || exit 0

VS Code Tasks

Add to .vscode/tasks.json:

{
    "label": "Organize Documentation",
    "type": "shell",
    "command": "./tools/docs-organizer/organize.sh",
    "args": ["docs/"],
    "group": "build",
    "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared"
    }
}

📝 Classification Logic

Time Buckets

• Today - Files modified today
• Yesterday - Files modified yesterday
• Week Prior - Files from the past week
• Historical - Older files

SDLC Phases

• Planning - Architecture, design documents
• Implementation - Development, feature docs
• Testing - Test plans, validation docs
• Debugging - Bug fixes, issue resolution
• Enhancement - UX improvements, optimizations
• Documentation - Guides, README files
• Completion - Success reports, summaries

System Functions

• Admin Tools - Management, configuration
• UI Components - Frontend, user interface
• Integration - System connections, APIs
• Content Management - Data, content handling
• Diagnostics - Analysis, monitoring
• Success Reports - Achievements, outcomes

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add your enhancements
4. Submit a pull request

Adding New Classifications

To add new organizational facets:

1. Create classification function
2. Add directory structure in create_base_structure()
3. Update organize_documentation() to use new classifier
4. Enhance generate_documentation_index() for new sections

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Designed for markdown-heavy projects
• Optimized for VS Code development environments
• Inspired by knowledge management best practices

---

Made with ❤️ for better documentation organization

🤖 AI Integration

For AI Assistants

The best practices extractor generates AI-friendly instructions:

# Current vs Deprecated Practices
- Focus on by-recency/latest/ and current-practices.md
- Avoid patterns listed in deprecated-practices.md
- Reference evolution-timeline.md for context

# Architecture Decisions
- Reference by-category/architecture/ for established patterns
- Consider proven approaches before proposing new ones

# Implementation Guidance  
- Start with by-category/development/ for current patterns
- Check deprecated-practices.md to avoid superseded approaches

Regenerating Intelligence

# Update practices based on recent commits
./extract-practices.sh . --clean

# Analyze longer history for more context
./extract-practices.sh . -m 12 -s 3

# Focus on high-significance changes only
./extract-practices.sh . -s 4

The system learns from your Git history to provide increasingly accurate guidance about what works and what doesn't in your specific project context.