Documentation Update Workflow

# Standard development workflow with documentation
git checkout -b feature/new-feature

# 1. Write code
# 2. Write/update documentation
# 3. Test both code and documentation
git add . && git commit -m "feat: add new feature with documentation"
git push origin feature/new-feature

# 4. Create PR with both code and documentation changes

## Documentation Impact Assessment

**Feature**: Multi-project workspace support
**Developer**: @your-username
**Documentation Impact**: High

### Required Documentation Updates

- [x] User guide for workspace configuration
- [x] CLI reference for new commands
- [x] Configuration reference for workspace settings
- [x] Examples for multi-project scenarios
- [x] Troubleshooting for workspace issues

### New Documentation Needed

- [x] New user guide: "Managing Multiple Projects"
- [x] New developer guide: "Workspace Architecture"
- [x] Updated examples: CLI usage with workspaces

# 1. Create feature branch
git checkout -b feature/multi-project-support

# 2. Create documentation structure first
mkdir -p docs/users/detailed-guides/workspace-management
touch docs/users/detailed-guides/workspace-management/README.md

# 3. Write initial documentation outline
# (Use feature template from templates/feature-template.md)

# 4. Implement feature code
# ... code development ...

# 5. Update documentation with actual implementation details
# ... documentation updates ...

# 6. Test both code and documentation
make test
# Test all documentation examples manually

# 7. Commit together
git add .
git commit -m "feat: add multi-project workspace support

- Add workspace configuration system
- Add CLI commands for workspace management
- Add user guide for workspace setup
- Add developer documentation for workspace architecture
- Add examples and troubleshooting

Closes #123"

# Find all documentation that mentions the feature
grep -r "workspace" docs/ --include="*.md"
grep -r "multi-project" docs/ --include="*.md"

# Check for configuration references
grep -r "workspace_config" docs/ --include="*.md"

# 1. Create branch for changes
git checkout -b fix/workspace-configuration-update

# 2. Identify affected documentation
echo "Affected documentation files:" > doc_update_plan.md
grep -l "workspace" docs/**/*.md >> doc_update_plan.md

# 3. Update code
# ... implement changes ...

# 4. Update documentation systematically
# Start with CLI reference, then user guides, then examples

# 5. Test updated examples
# Run through all examples in updated documentation

# 6. Commit with clear documentation changes
git add .
git commit -m "fix: update workspace configuration handling

Code changes:
- Fix workspace config validation
- Improve error messages

Documentation changes:
- Update configuration reference
- Fix examples in workspace guide
- Add new troubleshooting section

Fixes #456"

# 1. Identify if bug affects documented behavior
# If yes, update documentation

# 2. Add to troubleshooting if it's a common issue
# docs/users/troubleshooting/common-issues.md

# 3. Update examples if they were incorrect
# Test all related examples

# 4. Update error message documentation if changed
# docs/users/troubleshooting/error-messages-reference.md

# In troubleshooting/common-issues.md

#### Issue: Workspace Configuration Not Loading

**Symptoms**:

- Error: "Workspace configuration file not found"
- Default configuration used instead of workspace config

**Cause**: Bug in configuration file discovery (fixed in v1.2.1)

**Solution**:

```bash
# Ensure workspace config is in the correct location
ls -la config.yaml

# If missing, create with:
qdrant-loader init --workspace .

# 1. Update CLI reference first
# docs/users/cli-reference/commands.md

# 2. Update all user guides that use the CLI
grep -r "qdrant-loader" docs/users/

# 3. Update examples and code snippets
# Test all examples with new CLI

# 4. Add migration guide if needed (for breaking changes)
# docs/users/migration/cli-changes.md

# 5. Update troubleshooting for new error messages

# 1. Add new CLI documentation
# 2. Update examples to show new capabilities
# 3. Add to feature guides where relevant
# 4. No migration documentation needed

## Documentation Self-Review Checklist

### Content Quality

- [ ] **Purpose is clear** - Reader knows what they'll learn
- [ ] **Prerequisites listed** - Required setup is documented
- [ ] **Examples work** - All code examples tested
- [ ] **Steps are complete** - No missing steps in procedures
- [ ] **Outcomes described** - What success looks like

### Technical Accuracy

- [ ] **Commands tested** - All CLI commands work as shown
- [ ] **Config examples valid** - All YAML examples are valid
- [ ] **Implementation verified** - Matches actual codebase
- [ ] **Version info correct** - Requirements and compatibility accurate

### Structure and Navigation

- [ ] **File location correct** - Follows documentation structure
- [ ] **Cross-references added** - Links to related documentation
- [ ] **Navigation updated** - README files updated if needed
- [ ] **Formatting consistent** - Follows style guide

### User Experience

- [ ] **Audience appropriate** - Content matches intended users
- [ ] **Flow logical** - Information builds appropriately
- [ ] **Troubleshooting included** - Common issues addressed
- [ ] **Related docs linked** - Easy to find related information

## Documentation Review Guidelines

### Review Focus Areas

1. **Accuracy**: Do the examples work? Are the commands correct?
2. **Completeness**: Are there missing steps or information?
3. **Clarity**: Is it easy to understand and follow?
4. **Consistency**: Does it follow our style guide?

### Review Comments Format

Use this format for documentation feedback:

**Issue**: [Describe the problem]
**Suggestion**: [Provide specific improvement]
**Priority**: [High/Medium/Low]

Example:
**Issue**: The configuration example is missing the required `api_key` field
**Suggestion**: Add `api_key: "your-api-key-here"` to the YAML example
**Priority**: High

# Test CLI commands manually
qdrant-loader init --workspace .
qdrant-loader ingest --workspace .
qdrant-loader config --workspace .

# Validate YAML configuration files
python -c "import yaml; yaml.safe_load(open('config.yaml'))"

# Check for broken internal links manually
# (No automated tools currently available)

# .github/workflows/docs.yml (actual workflow)
name: Documentation Website
on:
  push:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'README.md'
      - 'website/**'

jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Build website using templates
        run: |
          python website/build.py \
            --output site \
            --templates website/templates

# Verify CLI commands work
qdrant-loader --help
qdrant-loader init --help
qdrant-loader ingest --help

# Check configuration examples
cd examples/workspace
qdrant-loader config --workspace .

# Validate project structure
make test # Run actual test suite

# 1. Implement the command in packages/qdrant-loader/src/qdrant_loader/cli/
# 2. Update CLI reference
echo "## qdrant-loader new-command" >> docs/users/cli-reference/commands.md

# 3. Add to user guide if it's a major feature
# 4. Add examples
# 5. Update help text documentation

# 1. Update configuration reference
# docs/users/configuration/config-file-reference.md

# 2. Update all examples that use the old format
grep -r "old_config_format" docs/ --include="*.md"

# 3. Add migration guide if breaking
# docs/users/migration/config-migration.md

# 4. Update troubleshooting for new validation errors

# 1. Create new data source guide
cp docs/users/detailed-guides/data-sources/git-repositories.md \
   docs/users/detailed-guides/data-sources/new-source.md

# 2. Update data sources overview
# docs/users/detailed-guides/data-sources/README.md

# 3. Add configuration documentation
# 4. Add examples and troubleshooting
# 5. Update main README if it's a major addition

# Test CLI commands
qdrant-loader init --workspace .
qdrant-loader ingest --workspace .
qdrant-loader config --workspace .
qdrant-loader project list --workspace .

# Find references to a feature
grep -r "feature_name" docs/ --include="*.md"

# Validate YAML configuration
python -c "import yaml; yaml.safe_load(open('config.yaml'))"

When adding documentation, place it in:
- User guides: docs/users/detailed-guides/
- Configuration: docs/users/configuration/
- CLI reference: docs/users/cli-reference/
- Troubleshooting: docs/users/troubleshooting/
- Developer guides: docs/developers/

# Main commands
qdrant-loader init [--force]
qdrant-loader ingest [--project PROJECT] [--source-type TYPE] [--source SOURCE]
qdrant-loader config

# Project management
qdrant-loader project list [--format json]
qdrant-loader project status [--project-id PROJECT] [--format json]
qdrant-loader project validate [--project-id PROJECT]

# Global options
--workspace PATH     # Workspace directory
--config PATH        # Configuration file (alternative to workspace)
--env PATH           # Environment file (alternative to workspace)
--log-level LEVEL    # Logging level