POWR/docs/project/documentation/organization_plan.md

POWR App Documentation Organization Plan

Last Updated: 2025-03-26
Status: Active
Related To: Documentation Standards, Project Organization

Purpose

This document outlines the plan for reorganizing the POWR app documentation to improve consistency, accessibility, and maintainability.

Current Documentation Issues

After examining our documentation structure, we've identified several issues:

1. Inconsistent organization: Some documents are in feature-specific folders while others are directly in the /design/ directory
2. Scattered analysis documents: Technical analysis documents are spread across different locations
3. Redundant documentation: Multiple files covering the same features with overlapping information
4. Poor visibility of key documents: Critical documents like MVPandTargetedRebuild.md aren't prominently placed
5. Inconsistent naming conventions: Mix of camelCase, PascalCase, and snake_case in folder and file names
6. Outdated documentation: Some documents no longer reflect current implementation or plans

Proposed Documentation Structure

docs/
├── guides/                          # Developer guides and practices
│   ├── coding_style.md                # Coding standards and practices
│   ├── ai_collaboration_guide.md      # How to work with AI tools
│   ├── documentation_guide.md         # How to write and maintain docs
│   └── writing_good_interfaces.md     # Interface design principles
│
├── architecture/                    # System-wide architectural documentation
│   ├── system_overview.md             # High-level system architecture
│   ├── data_flow.md                   # App-wide data flow patterns
│   ├── database_architecture.md       # Database design and schema
│   ├── state_management.md            # State management approach
│   └── offline_support.md             # Offline functionality architecture
│
├── features/                        # Feature-specific documentation
│   ├── workout/                       # Workout feature documentation
│   │   ├── workout_overview.md          # Feature overview
│   │   ├── ui_components.md             # UI component specifications
│   │   ├── data_models.md               # Data models and interfaces
│   │   ├── completion_flow.md           # Workout completion flow
│   │   └── implementation_roadmap.md    # Implementation plan
│   │
│   ├── social/                        # Social feature documentation
│   │   ├── social_overview.md           # Feature overview
│   │   ├── architecture.md              # Social feature architecture
│   │   ├── feed_implementation.md       # Feed implementation details
│   │   ├── caching_strategy.md          # Caching approach
│   │   └── filtering_rules.md           # Content filtering rules
│   │
│   ├── profile/                       # Profile feature documentation
│   │   └── profile_enhancement.md       # Profile tab enhancements
│   │
│   ├── library/                       # Library feature documentation
│   │   ├── library_overview.md          # Feature overview
│   │   └── template_organization.md     # Template organization
│   │
│   ├── powr_packs/                    # POWR Packs feature documentation
│   │   ├── overview.md                  # Feature overview
│   │   └── implementation_plan.md       # Implementation plan
│   │
│   ├── history/                       # History feature documentation
│   │   ├── history_overview.md          # Feature overview
│   │   └── migration_guide.md           # Migration guide
│   │
│   └── settings/                      # Settings feature documentation
│       └── implementation_guide.md     # Implementation guide
│
├── technical/                       # Technical documentation
│   ├── ndk/                           # NDK-related documentation
│   │   ├── comprehensive_guide.md       # Comprehensive NDK guide
│   │   ├── subscription_analysis.md     # Subscription handling analysis
│   │   └── encoding_decoding.md         # NIP-19 encoding/decoding
│   │
│   ├── caching/                       # Caching documentation
│   │   └── cache_implementation.md      # Cache implementation details
│   │
│   ├── styling/                       # Styling documentation
│   │   └── styling_guide.md            # Styling approach and patterns
│   │
│   └── nostr/                         # Nostr protocol documentation
│       └── exercise_nip.md             # Nostr exercise NIP
│
├── testing/                         # Testing documentation
│   ├── testing_strategy.md            # Overall testing approach
│   ├── cache_testing.md               # Cache implementation testing
│   └── contact_service_tests.md       # Contact service testing
│
├── project/                         # Project management documentation
│   ├── mvp_and_rebuild.md             # MVP and targeted rebuild plan
│   ├── roadmap.md                     # Project roadmap
│   ├── release_process.md             # Release process documentation
│   └── documentation/                 # Documentation about documentation
│       ├── organization_plan.md         # This document
│       ├── review_process.md            # Documentation review process
│       ├── implementation_script.md     # Implementation scripts
│       ├── migration_mapping.md         # Source → destination mapping
│       └── standards.md                 # Documentation standards
│
├── tools/                          # Documentation tools
│   ├── doc-migrator.js               # Migration script
│   ├── check-links.js                # Link validation script  
│   └── README.md                     # Tool documentation
│
└── archive/                         # Archived/obsolete documentation
    └── [outdated documents]           # Outdated documentation files

Implementation Strategy

1. Create New Structure: Create the new folder structure while preserving existing files
2. Document Review: Review all existing documentation using the review_process.md criteria
3. Migrate Content:
   • Move files to their appropriate locations in the new structure
   • Rename files to follow consistent conventions
   • Update cross-references between documents
4. Consolidate Documentation:
   • Merge redundant documentation
   • Create new overview documents for each major feature area
5. Archive Outdated Content:
   • Move obsolete documentation to the archive folder
   • Add notices to archived docs indicating they're outdated
6. Update References:
   • Search codebase for references to documentation
   • Update any links in code comments or README files
7. Documentation Index:
   • Create an index file for each major section
   • Add a main index.md at the root of the docs directory

File Naming Conventions

• Use snake_case for all documentation filenames for consistency
• Use descriptive but concise names that clearly indicate content
• For feature-specific docs, prefix with feature name: social_architecture.md
• For technical docs, use descriptive names: subscription_analysis.md

Content Guidelines

• Each document should begin with a clear title and purpose statement
• Include a last-updated date in each document
• Include a table of contents for longer documents
• Use consistent heading levels (# for title, ## for major sections, etc.)
• Include code examples where appropriate
• Link to related documentation when referencing other concepts
• Include diagrams for complex systems or flows

Priority Documents

The following documents should be prioritized in the migration process:

1. docs/project/mvp_and_rebuild.md (moved from MVPandTargetedRebuild.md)
2. docs/technical/ndk/comprehensive_guide.md (moved from NDK_Comprehensive_Guide.md)
3. docs/features/social/architecture.md (consolidated from social docs)
4. docs/architecture/database_architecture.md (updated from existing)
5. docs/guides/coding_style.md (moved from root)

Document Example: Migration Template

For each document that needs to be migrated, use this template:

# [Document Title]

**Last Updated:** [Date]
**Status:** [Active/Archived/Draft]
**Related To:** [Feature/Component]

## Purpose

Brief description of this document's purpose.

## Content

Main document content goes here.

## Related Documentation

- [Link to related doc 1]
- [Link to related doc 2]

Success Criteria

The documentation reorganization will be considered successful when:

1. All documentation follows the new structure
2. No redundant documentation exists in multiple locations
3. All documentation is updated to reflect current implementation or plans
4. Key MVP-related documentation is prominently accessible
5. Naming conventions are consistent throughout
6. All cross-references between documents are functional
7. Obsolete documents are properly archived
8. New documentation is created to fill important gaps

Related Documentation

• Documentation Review Process - How to review documentation for quality and accuracy
• Documentation Migration Implementation - Specific implementation details
• Documentation Migration Mapping - Mapping of source files to destinations
• Documentation Standards - Detailed documentation standards