Documentation Reorganization Plan

Overview

Based on the documentation review and answered questions, here's a plan to reorganize the documentation for better clarity and implementation guidance.

Current Structure

docs/
├── cli/                    # 9 files covering all CLI commands
├── directory-structure/    # 1 file showing .gira/ layout
├── planning/              # 1 file with implementation phases
├── project-structure/     # 1 file with technical architecture
├── DOCUMENTATION_REVIEW.md # Review with answered questions
└── MISSING_DOCUMENTATION.md # Gaps to fill

Proposed New Structure

Phase 1: Core Reorganization (Immediate)

1. Create overview section

   mkdir -p docs/00-overview
   # Move and rename files:
   # - Create README.md with project overview
   # - Move PROJECT_STRUCTURE.md → architecture.md
   # - Create concepts.md (extract from existing docs)
   

2. Create getting-started section

   mkdir -p docs/01-getting-started
   # Move and rename:
   # - cli/01_initialization_and_configuration.md → initialization.md
   # - Create installation.md (new)
   # - Create quickstart.md (new)
   

3. Consolidate user guide

   mkdir -p docs/02-user-guide
   # Move CLI docs here with cleaner names:
   # - cli/02_ticket_management.md → tickets.md
   # - cli/03_epic_management.md → epics.md
   # - cli/04_sprint_management.md → sprints.md
   # - cli/05_comments_and_collaboration.md → comments.md
   # - cli/06_attachments.md → attachments.md
   # - cli/09_subtasks_and_dependencies.md → subtasks.md
   # - Create workflows.md (new, based on answered questions)
   

4. Create integrations section

   mkdir -p docs/03-integrations
   # Move:
   # - cli/07_jira_integration.md → jira.md
   # Create new:
   # - github.md
   # - ai-agents.md
   

5. Create administration section

   mkdir -p docs/04-administration
   # Move:
   # - cli/08_reports_and_utilities.md → reports.md
   # Extract and create:
   # - configuration.md (from initialization)
   # - maintenance.md (archive, validate commands)
   # - migration.md (new)
   

6. Create reference section

   mkdir -p docs/05-reference
   # Move:
   # - directory-structure/directory-structure.md → directory-structure.md
   # Create:
   # - cli-reference.md (complete command list)
   # - file-formats.md (JSON schemas)
   # - api.md (Python API docs)
   

7. Create development section

   mkdir -p docs/06-development
   # Move:
   # - planning/HIGH_LEVEL_PLAN.md → implementation-plan.md
   # - DOCUMENTATION_REVIEW.md → design-decisions.md
   # - MISSING_DOCUMENTATION.md → todo.md
   # Create:
   # - contributing.md
   # - testing.md
   

Phase 2: Content Creation (Priority Order)

1. Week 1: Essential Getting Started
2. installation.md - System requirements, pip/pipx install
3. quickstart.md - 5-minute tutorial

4. concepts.md - Core concepts explained

5. Week 2: Technical References

6. file-formats.md - JSON schemas from MISSING_DOCUMENTATION.md
7. cli-reference.md - Complete command reference

8. workflows.md - Based on answered workflow questions

9. Week 3: Integration & Advanced

10. github.md - Git workflows and CI/CD
11. ai-agents.md - AI integration patterns

12. api.md - Python API documentation

13. Week 4: Team & Maintenance

14. migration.md - Moving from other systems
15. maintenance.md - Best practices
16. contributing.md - Development guide

Migration Script

#!/bin/bash
# docs/reorganize.sh

# Create new structure
mkdir -p docs/{00-overview,01-getting-started,02-user-guide,03-integrations,04-administration,05-reference,06-development}

# Move files with git mv to preserve history
git mv docs/project-structure/PROJECT_STRUCTURE.md docs/00-overview/architecture.md
git mv docs/cli/01_initialization_and_configuration.md docs/01-getting-started/initialization.md
git mv docs/cli/02_ticket_management.md docs/02-user-guide/tickets.md
git mv docs/cli/03_epic_management.md docs/02-user-guide/epics.md
git mv docs/cli/04_sprint_management.md docs/02-user-guide/sprints.md
git mv docs/cli/05_comments_and_collaboration.md docs/02-user-guide/comments.md
git mv docs/cli/06_attachments.md docs/02-user-guide/attachments.md
git mv docs/cli/09_subtasks_and_dependencies.md docs/02-user-guide/subtasks.md
git mv docs/cli/07_jira_integration.md docs/03-integrations/jira.md
git mv docs/cli/08_reports_and_utilities.md docs/04-administration/reports.md
git mv docs/directory-structure/directory-structure.md docs/05-reference/directory-structure.md
git mv docs/planning/HIGH_LEVEL_PLAN.md docs/06-development/implementation-plan.md
git mv docs/DOCUMENTATION_REVIEW.md docs/06-development/design-decisions.md
git mv docs/MISSING_DOCUMENTATION.md docs/06-development/todo.md

# Remove old directories
rmdir docs/cli docs/directory-structure docs/planning docs/project-structure

Benefits of New Structure

1. Logical Flow: Overview → Getting Started → User Guide → Advanced Topics
2. Easier Navigation: Numbered sections show progression
3. Clear Separation: User docs vs developer docs
4. Implementation Ready: Aligns with phased development plan
5. Extensible: Easy to add new docs in appropriate sections

Next Steps

1. Execute the reorganization script
2. Create placeholder files for missing documentation
3. Add navigation README.md in each section
4. Update root docs/README.md with table of contents
5. Begin filling in missing documentation per priority order