POWR/docs/project/documentation/implementation_script.md

Documentation Reorganization Implementation Script

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

Purpose

This document provides a practical, step-by-step approach to implementing the documentation reorganization outlined in the organization plan. It includes specific commands, actions, and validation steps to ensure a smooth migration process.

Prerequisites

• Git command line tools
• Access to repository
• Node.js (for running any scripts we might create)
• Text editor for modifying files

Phase 1: Setup and Preparation

1. Create a dedicated branch for documentation updates

git checkout -b docs/reorganization

2. Create the new folder structure

# Create the main directory structure
mkdir -p docs/guides
mkdir -p docs/architecture
mkdir -p docs/features/workout
mkdir -p docs/features/social
mkdir -p docs/features/profile
mkdir -p docs/features/library
mkdir -p docs/features/powr_packs
mkdir -p docs/features/history
mkdir -p docs/features/settings
mkdir -p docs/technical/ndk
mkdir -p docs/technical/caching
mkdir -p docs/technical/styling
mkdir -p docs/technical/nostr
mkdir -p docs/testing
mkdir -p docs/project
mkdir -p docs/project/documentation
mkdir -p docs/tools
mkdir -p docs/archive

3. Create placeholders for critical new documents

touch docs/index.md
touch docs/guides/index.md
touch docs/architecture/index.md
touch docs/features/index.md
touch docs/technical/index.md
touch docs/testing/index.md
touch docs/project/index.md

Phase 2: Migration of High-Priority Documents

1. Move the MVP and Targeted Rebuild document

cp docs/design/MVPandTargetedRebuild.md docs/project/mvp_and_rebuild.md

Update the document with a new header that includes:

• Last updated date
• Status: Active
• Add proper cross-references to other documents

2. Move the NDK Comprehensive Guide

cp docs/design/Analysis/NDK_Comprehensive_Guide.md docs/technical/ndk/comprehensive_guide.md

Update the document with:

• Last updated date
• Status: Active
• Cross-references to other NDK-related documents

3. Consolidate Social Architecture Documentation

Review and merge insights from:

• docs/design/Social/POWRSocialArchitecture.md
• docs/design/Social/POWRSocialFeedImplementationPlan.md
• docs/design/Social/UpdatedPlan.md

touch docs/features/social/architecture.md

Create a comprehensive document that consolidates the key information.

4. Update Database Architecture Documentation

cp docs/design/database_architecture.md docs/architecture/database_architecture.md

Update with latest database schema and patterns.

5. Move Coding Style Guide

cp docs/coding_style.md docs/guides/coding_style.md

Phase 3: Iterative Content Migration

For each remaining document, follow this process:

1. Review using the review process criteria
2. Determine whether to:
   • Migrate (with updates)
   • Consolidate with other documents
   • Archive as outdated
3. Update content and move to new location

Migration Script

Create a simple node script to assist with migrations:

// doc-migrator.js
const fs = require('fs');
const path = require('path');

// Usage: node doc-migrator.js <source> <destination> <title> <status>
const [source, destination, title, status] = process.argv.slice(2);

if (!source || !destination || !title || !status) {
  console.error('Usage: node doc-migrator.js <source> <destination> <title> <status>');
  process.exit(1);
}

// Read source content
console.log(`Reading source file: ${source}`);
const sourceContent = fs.readFileSync(source, 'utf8');

// Create new content with template
const today = new Date().toISOString().slice(0, 10);
const newContent = `# ${title}

**Last Updated:** ${today}  
**Status:** ${status}  
**Related To:** [Fill in related component]

## Purpose

[Brief description of this document's purpose]

${sourceContent.replace(/^# .+(\r?\n|\r)/, '')}

## Related Documentation

- [Add related document links]
`;

// Ensure destination directory exists
const destDir = path.dirname(destination);
if (!fs.existsSync(destDir)) {
  fs.mkdirSync(destDir, { recursive: true });
}

// Write new file
console.log(`Writing to destination: ${destination}`);
fs.writeFileSync(destination, newContent);
console.log(`Successfully migrated ${source} to ${destination}`);

// Create a simple link checker to help validate links
const checkLinksScript = `
const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

const docsRoot = path.resolve(__dirname, '..');

// Get all markdown files
const allMdFiles = execSync(\`find \${docsRoot} -name "*.md"\`).toString().split('\\n').filter(Boolean);

// Track all files and links
const allFiles = new Set(allMdFiles.map(f => path.relative(docsRoot, f)));
const brokenLinks = [];

allMdFiles.forEach(file => {
  const content = fs.readFileSync(file, 'utf8');
  const relativeFile = path.relative(docsRoot, file);
  
  // Find markdown links
  const linkRegex = /\\[.*?\\]\\((.*?)\\)/g;
  let match;
  
  while ((match = linkRegex.exec(content)) !== null) {
    const link = match[1];
    
    // Skip external links and anchors
    if (link.startsWith('http') || link.startsWith('#')) continue;
    
    // Resolve relative to the file
    const fileDir = path.dirname(relativeFile);
    const resolvedLink = path.normalize(path.join(fileDir, link));
    
    // Check if file exists
    if (!allFiles.has(resolvedLink)) {
      brokenLinks.push({ file: relativeFile, link, resolvedLink });
    }
  }
});

if (brokenLinks.length > 0) {
  console.log('Found broken links:');
  brokenLinks.forEach(({ file, link, resolvedLink }) => {
    console.log(\`In \${file}: Broken link \${link} (resolves to \${resolvedLink})\`);
  });
  process.exit(1);
} else {
  console.log('All links are valid!');
}
`;

fs.writeFileSync('check-links.js', checkLinksScript);
console.log('Created link checker script: check-links.js');

Run this script for each document to migrate:

node doc-migrator.js docs/design/WorkoutCompletion.md docs/features/workout/completion_flow.md "Workout Completion Flow" "Active"

Phase 4: Archive Outdated Documents

For documents determined to be outdated:

# Example
mkdir -p docs/archive/social
cp docs/design/Social/OldImplementationPlan.md docs/archive/social/old_implementation_plan.md

Add an archive notice at the top:

> **ARCHIVED DOCUMENT**: This document is outdated and kept for historical reference only. Please refer to [Current Document](path/to/current/doc.md) for up-to-date information.

Phase 5: Create Index Documents

For each section, create an index document that lists and describes the contents:

# Technical Documentation

This section contains technical documentation for various aspects of the POWR app.

## Contents

- [NDK Documentation](./ndk/index.md): Nostr Development Kit implementation details
- [Caching Documentation](./caching/index.md): Caching strategies and implementations
- [Styling Documentation](./styling/index.md): Styling approach and patterns
- [Nostr Documentation](./nostr/index.md): Nostr protocol implementation details

Phase 6: Update References

1. Search for document references in the codebase

grep -r "docs/design" --include="*.ts" --include="*.tsx" .

2. Update each reference to point to the new location

3. Update cross-references between documents

Phase 7: Validation and Testing

1. Verify all links work

Use the link checker script created during the migration process:

node docs/tools/check-links.js

2. Manual review of most critical documents

Phase 8: Commit Changes

git add docs
git commit -m "Reorganize documentation to improve structure and discoverability

- Implemented new folder structure for better organization
- Migrated key documents to appropriate locations
- Updated content with consistent formatting
- Created index files for better navigation
- Archived outdated documents
- Fixed cross-references between documents"

git push origin docs/reorganization

Phase 9: Create Pull Request

Create a pull request with a detailed description of changes, including:

1. Overview of reorganization
2. Summary of major content updates
3. Instructions for developers to find documentation they previously used

Success Checklist

• All documents follow the new structure
• No redundant documentation exists
• All documentation reflects current implementation or plans
• Key MVP documentation is prominently placed
• Naming conventions are consistent throughout
• All cross-references between documents work
• Obsolete documents are properly archived
• New documentation fills important gaps
• Main index.md provides clear navigation

Related Documentation

• Documentation Organization Plan - Overall documentation organization strategy
• Documentation Review Process - Process for reviewing documentation quality
• Documentation Migration Mapping - Mapping of source files to destinations
• Documentation Standards - Detailed documentation standards