# Documentation Maintenance Guide

This guide helps developers understand which documentation files need updating when making changes to Bangstack.

## Quick Impact Matrix

Use this table to quickly identify which docs need updates:

| Change Type | Files to Update | Priority |
|-------------|----------------|----------|
| **New CLI Command** | QUICK-REFERENCE.md, README.md | High |
| **Changed CLI Flag** | QUICK-REFERENCE.md, tutorials/*.md | High |
| **New Generator** | README.md, QUICK-REFERENCE.md, GENERATOR-FRAMEWORK.md | High |
| **API Function Change** | API-REFERENCE.md | High |
| **Schema Change** | EXTENDED-SCHEMA-GUIDE.md, QUICK-REFERENCE.md, tutorials/*.md | High |
| **New Field Type** | QUICK-REFERENCE.md, EXTENDED-SCHEMA-GUIDE.md | Medium |
| **New Tech Stack Option** | QUICK-REFERENCE.md, tutorials/BUILD-A-BLOG-IN-5-MINUTES.md | Medium |
| **Auth Feature Change** | tutorials/ADD-AUTHENTICATION.md, AUTH-SYSTEM-GUIDE.md | Medium |
| **Bug Fix** | None (unless fixes documented behavior) | Low |
| **Refactoring** | None (unless changes public API) | Low |

## Detailed Change Scenarios

### 1. Adding a New CLI Command

**Example:** Adding `bang deploy` command

**Files to update:**

1. **README.md** (`src/cli/index.ts:28-38`)
   ```markdown
   ## 🛠️ CLI Commands

   ### `bang deploy`  // ADD THIS
   ```

2. **QUICK-REFERENCE.md** (`docs/QUICK-REFERENCE.md:11-36`)
   ```markdown
   ### Basic Commands

   # Deploy application
   bang deploy                    // ADD THIS
   ```

3. **INDEX.md** (if major command)
   - Add to relevant learning paths

**Testing:**
```bash
# Verify command works as documented
bang deploy --help
```

### 2. Adding a New Generator

**Example:** Adding VueGenerator

**Files to update:**

1. **README.md** (`src/generators/index.ts:50-51`)
   ```markdown
   - 🎨 **Multiple Generators** - React, Vue, Express...  // UPDATE LIST
   ```

2. **QUICK-REFERENCE.md** (`docs/QUICK-REFERENCE.md:154-162`)
   ```markdown
   ### Frontend

   type: vue            # Vue.js  // ADD THIS
   ```

3. **GENERATOR-FRAMEWORK.md**
   - Add Vue to list of built-in generators
   - Add example if significantly different

4. **tutorials/CUSTOM-GENERATORS.md** (optional)
   - Consider adding Vue as an example

5. **INDEX.md**
   - Update documentation metrics

**Testing:**
```bash
# Verify generator appears
bang list-generators | grep -i vue

# Test generation
bang generate test-vue-workflow.yaml
```

### 3. Changing the Workflow Schema

**Example:** Adding `cache` to technology section

**Files to update:**

1. **EXTENDED-SCHEMA-GUIDE.md**
   ```yaml
   technology:
     cache:              # ADD THIS SECTION
       type: redis
   ```

2. **QUICK-REFERENCE.md**
   ```markdown
   ### Cache

   technology:
     cache:              # ADD THIS
   ```

3. **tutorials/BUILD-A-BLOG-IN-5-MINUTES.md**
   - Update example if cache is common use case

4. **API-REFERENCE.md**
   - Update ExtendedWorkflow type definition

**Testing:**
```bash
# Create workflow with cache config
# Verify it validates and generates
bang validate test-cache.workflow.yaml
bang generate test-cache.workflow.yaml
```

### 4. Changing a Public API Function

**Example:** Changing `generateFromWorkflow()` signature

**Files to update:**

1. **API-REFERENCE.md** (`docs/API-REFERENCE.md:16-46`)
   ```typescript
   async function generateFromWorkflow(options) {
     // Update signature and example
   }
   ```

2. **tutorials/CUSTOM-GENERATORS.md** (if used in examples)
   - Update any code examples

**Testing:**
```typescript
// Test that documented examples actually work
import { generateFromWorkflow } from 'bangstack';
// Run example from docs
```

### 5. Adding Authentication Features

**Example:** Adding MFA support

**Files to update:**

1. **tutorials/ADD-AUTHENTICATION.md** (`docs/tutorials/ADD-AUTHENTICATION.md`)
   - Add MFA section with examples

2. **AUTH-SYSTEM-GUIDE.md**
   - Add detailed MFA implementation guide

3. **QUICK-REFERENCE.md**
   - Add MFA to authentication patterns

**Testing:**
```bash
# Generate workflow with MFA
bang generate mfa-test.workflow.yaml
# Verify MFA code is generated
```

## Maintenance Checklist

When making changes, use this checklist:

### Before Making Changes

- [ ] Identify which documentation category your change affects
- [ ] Check the impact matrix above
- [ ] Note which files will need updates

### While Making Changes

- [ ] Update code comments and JSDoc
- [ ] Add TODO comments for doc updates if needed
- [ ] Update test cases

### After Making Changes

- [ ] Update identified documentation files
- [ ] Test all code examples in updated docs
- [ ] Run workflow examples to verify they work
- [ ] Update version/last-updated metadata
- [ ] Check for broken internal links

### Before Committing

- [ ] Run documentation linter (if available)
- [ ] Build and preview docs locally
- [ ] Commit docs with descriptive message

## Documentation Categories by Maintenance Frequency

### High Frequency (Update Often)
- **QUICK-REFERENCE.md** - CLI commands, syntax changes
- **API-REFERENCE.md** - API changes
- **README.md** - New features, version updates

### Medium Frequency (Update Occasionally)
- **tutorials/*.md** - Major feature additions
- **EXTENDED-SCHEMA-GUIDE.md** - Schema changes
- **GENERATOR-FRAMEWORK.md** - New generator patterns

### Low Frequency (Rarely Update)
- **INDEX.md** - Only when structure changes
- **WORKFLOW-BEST-PRACTICES.md** - Conceptual content
- **Architecture docs** - Design changes only

## Automated Documentation Checks

### Current Manual Checks

1. **CLI Command Sync**
   ```bash
   # Compare CLI commands in docs vs actual
   grep "^bang " docs/QUICK-REFERENCE.md | sort
   bang --help | grep "^  " | sort
   # Should match!
   ```

2. **API Function Names**
   ```bash
   # Check API-REFERENCE.md mentions actual functions
   grep -E "^### \`\w+\(\)" docs/API-REFERENCE.md
   grep -E "^export (function|class)" src/**/*.ts
   ```

3. **Workflow Examples Valid**
   ```bash
   # Test all workflow examples in tutorials
   for file in docs/tutorials/*.md; do
     # Extract YAML blocks and validate
     bang validate extracted-workflow.yaml
   done
   ```

### Future Automated Checks (Recommended)

1. **Doc Test Suite**
   ```typescript
   // tests/docs/documentation.test.ts
   describe('Documentation Accuracy', () => {
     it('all CLI commands in QUICK-REFERENCE.md exist', () => {
       const docCommands = extractCommandsFromDocs();
       const actualCommands = getActualCliCommands();
       expect(docCommands).toEqual(actualCommands);
     });

     it('all API functions in API-REFERENCE.md exist', () => {
       const docFunctions = extractFunctionsFromDocs();
       const actualFunctions = getExportedFunctions();
       expect(docFunctions).toContain(actualFunctions);
     });

     it('all workflow examples are valid', async () => {
       const examples = extractWorkflowExamples();
       for (const example of examples) {
         const result = await validateWorkflow(example);
         expect(result.valid).toBe(true);
       }
     });
   });
   ```

2. **Pre-commit Hook**
   ```bash
   #!/bin/bash
   # .git/hooks/pre-commit

   # Check if API code changed
   if git diff --cached --name-only | grep -q "^src/.*\.ts$"; then
     echo "⚠️  Source code changed. Remember to update API-REFERENCE.md"
   fi

   # Check if CLI changed
   if git diff --cached --name-only | grep -q "src/cli/"; then
     echo "⚠️  CLI code changed. Remember to update QUICK-REFERENCE.md"
   fi

   # Check if generators changed
   if git diff --cached --name-only | grep -q "src/generators/"; then
     echo "⚠️  Generators changed. Remember to update README.md"
   fi
   ```

3. **CI Documentation Check**
   ```yaml
   # .github/workflows/docs-check.yml
   name: Documentation Check

   on: [pull_request]

   jobs:
     check-docs:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - name: Check for doc updates
           run: |
             # If src/ changed but docs/ didn't, warn
             if git diff --name-only origin/main | grep -q "^src/" && \
                ! git diff --name-only origin/main | grep -q "^docs/"; then
               echo "::warning::Source code changed but no documentation updates"
             fi
   ```

## AI-Assisted Documentation Updates

When using Claude Code or similar AI tools to update documentation:

### Effective Prompts

**For CLI changes:**
```
I changed the CLI command `bang generate` to add a new flag `--parallel`.
Please update all documentation files that reference this command.
```

**For API changes:**
```
I modified the `generateFromWorkflow()` function to accept a new
`options.plugins` parameter. Please update API-REFERENCE.md and any
tutorials that use this function.
```

**For schema changes:**
```
I added a new `technology.cache` section to the extended workflow schema.
Please update:
1. EXTENDED-SCHEMA-GUIDE.md
2. QUICK-REFERENCE.md
3. Any relevant tutorials
```

### Context to Provide

Always include:
1. What changed (code diff or description)
2. Why it changed (use case)
3. Example usage (if applicable)
4. Which docs you think need updates

## Version-Specific Documentation

### Current Approach
- Single documentation set for current version
- Breaking changes noted in docs

### Recommended for v1.0+
```
docs/
├── v1.0/
│   ├── API-REFERENCE.md
│   └── ...
├── v2.0/
│   ├── API-REFERENCE.md
│   └── ...
└── latest -> v2.0/
```

## Documentation Metadata

### Add to Each Doc File

```markdown
---
version: 1.0.0
last_updated: 2025-10-13
applies_to: [">=1.0.0", "<2.0.0"]
related_files:
  - API-REFERENCE.md
  - EXTENDED-SCHEMA-GUIDE.md
---
```

### Benefits
- Track doc freshness
- Version compatibility
- Auto-link related docs

## Common Mistakes to Avoid

### ❌ Don't Do This

1. **Outdated Examples**
   ```yaml
   # Bad: Using old schema format
   stack:
     type: backend  # This syntax deprecated!
   ```

2. **Wrong Command Syntax**
   ```bash
   # Bad: Documenting non-existent flags
   bang generate --magic-flag  # This flag doesn't exist!
   ```

3. **Inconsistent Examples**
   ```markdown
   # Bad: Tutorial says PostgreSQL but examples use MySQL
   ```

### ✅ Do This Instead

1. **Test Examples**
   ```bash
   # Good: Actually run the command
   bang generate workflow.yaml
   ```

2. **Use Current Syntax**
   ```yaml
   # Good: Using current schema
   technology:
     backend:
       type: express
   ```

3. **Consistent Throughout**
   ```markdown
   # Good: Same tech stack throughout tutorial
   ```

## Getting Help

### Before Updating Docs

1. Check this guide's impact matrix
2. Review similar past doc updates (git history)
3. Ask in #documentation channel (if available)

### When Stuck

1. Look at existing similar documentation
2. Use git blame to see who wrote it
3. Create a draft PR and ask for review

### Reporting Doc Issues

```markdown
# Good issue report

**Documentation:** API-REFERENCE.md
**Section:** generateFromWorkflow()
**Issue:** Function signature doesn't match actual implementation
**Expected:** options.plugins parameter should be documented
**Actual:** Parameter is missing from docs
**Code reference:** src/index.ts:42
```

## Documentation Style Guide

### Voice and Tone
- Use second person ("you") for tutorials
- Use imperative mood for instructions ("Run this command")
- Be concise but not terse

### Code Examples
- Always test code examples before committing
- Include full working examples when possible
- Show both input and expected output

### Structure
- Use clear headings (H2 for major sections, H3 for subsections)
- Include table of contents for long docs
- Add "Next Steps" or "See Also" sections

## Summary: Is Documentation Maintainable?

### Short Answer
**Yes, with AI assistance** - Since you have access to Claude Code:
- Claude can identify which docs to update based on code changes
- The impact matrix in this guide helps target the right files
- Most updates are straightforward find-and-replace or add-section tasks

### Medium Answer
**Partially, with discipline** - Without AI:
- High-risk areas (CLI, API) need careful manual maintenance
- Impact matrix helps but requires developer diligence
- Conceptual docs are low maintenance

### Long Answer
**Should improve automation** - For best results:
1. Add documentation tests (CLI sync, API sync, example validation)
2. Use pre-commit hooks for reminders
3. Generate API docs from code when possible
4. Version documentation alongside code

## Action Items for Improving Maintainability

### Now (Easy Wins)
1. ✅ Use this maintenance guide for future updates
2. ✅ Add pre-commit hook with doc reminders
3. ✅ Create issue template for doc updates

### Soon (Medium Effort)
1. Add documentation tests to CI
2. Generate API reference from TypeScript
3. Extract CLI reference from Commander.js
4. Test workflow examples automatically

### Later (Long-term)
1. Version-specific documentation
2. Auto-generate parts of docs from code
3. Documentation linter with custom rules
4. Interactive documentation with live examples

---

**Remember:** Good documentation is a continuous process. Use this guide to make updates systematic and predictable.

**Questions?** Open an issue or ask in discussions!
