# 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: ```markdown # [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](./review_process.md) - How to review documentation for quality and accuracy - [Documentation Migration Implementation](./implementation_script.md) - Specific implementation details - [Documentation Migration Mapping](./migration_mapping.md) - Mapping of source files to destinations - [Documentation Standards](./standards.md) - Detailed documentation standards