# Documentation Examples

This directory contains before/after examples demonstrating good vs. bad documentation practices.

## Examples

### 1. Good PR Example

**File:** `good-pr-example.md`

Complete example of a well-documented pull request including:
- ✅ Proper PR title and description
- ✅ Complete documentation checklist
- ✅ Comprehensive docstrings
- ✅ Updated README with configuration and usage
- ✅ API documentation with examples
- ✅ Testing details and security considerations

**Use this as a reference when:**
- Creating a new feature PR
- Unsure what "complete documentation" means
- Need examples of good docstrings
- Writing API documentation

### 2. Bad PR Example

**File:** `bad-pr-example.md`

Examples of common documentation mistakes:
- ❌ Vague PR titles and descriptions
- ❌ Missing or incomplete docstrings
- ❌ No README updates
- ❌ Missing API documentation
- ❌ Unchecked documentation checklists

Plus guidance on how to fix each mistake.

**Use this to:**
- Understand what NOT to do
- Identify documentation gaps in your own PRs
- Learn from common mistakes
- Improve documentation quality

### 3. Complex Function Docstring Example

**File:** `example-docstring-complex-function.md`

Comprehensive example of documenting a complex function (retry decorator with exponential backoff):
- ✅ Complete Google-style docstring
- ✅ Detailed parameter descriptions with constraints
- ✅ Multiple usage examples (basic, advanced, edge cases)
- ✅ Exception documentation
- ✅ Notes on threading, performance, and limitations
- ✅ See Also section with related resources

**Use this as a reference when:**
- Writing docstrings for complex functions
- Documenting decorators, context managers, or metaclasses
- Need examples of comprehensive parameter documentation
- Unsure how detailed docstrings should be

### 4. API Documentation Example

**File:** `example-api-documentation.md`

Complete API documentation for a user authentication service:
- ✅ Table of contents and overview
- ✅ Detailed endpoint documentation (requests, responses, errors)
- ✅ Data models and field descriptions
- ✅ Error codes and recovery actions
- ✅ Rate limiting and security considerations
- ✅ Usage examples in multiple languages (Python, JavaScript, cURL)

**Use this as a reference when:**
- Documenting REST APIs
- Creating external API documentation
- Need examples of comprehensive endpoint documentation
- Documenting authentication/security features

### 5. README Before/After Example

**File:** `example-readme-before-after.md`

Side-by-side comparison showing how to update a README when adding JWT authentication:
- ✅ Before: Incomplete documentation (what NOT to do)
- ✅ After: Complete documentation with all new feature details
- ✅ Comparison table highlighting changes
- ✅ Configuration examples with comments
- ✅ Multiple usage examples
- ✅ Security best practices

**Use this as a reference when:**
- Updating README for new features
- Unsure what sections to update
- Need examples of good configuration documentation
- Adding security-related features

## How to Use These Examples

### For New Features

1. **Start with the good example**
   - Review the PR description structure
   - Check the documentation checklist
   - Note the level of detail in docstrings

2. **Adapt to your feature**
   - Use the same checklist format
   - Follow the same documentation patterns
   - Include similar testing details

3. **Compare to your PR**
   - Does your PR description explain what/why/impact?
   - Are all checklist items ✅?
   - Do you have usage examples?

### For Code Reviews

1. **Compare PR to good example**
   - Is the description as detailed?
   - Are all documentation areas covered?
   - Are usage examples provided?

2. **Check for bad patterns**
   - Vague descriptions?
   - Missing docstrings?
   - Unchecked checklists?

3. **Request improvements**
   - Point to specific examples
   - Suggest concrete improvements
   - Link to relevant sections

### For Learning

1. **Read both examples side-by-side**
2. **Identify the differences**
3. **Understand why the good example is better**
4. **Apply these patterns to your own work**

## Quick Comparison

| Aspect | Good Example | Bad Example | See Example |
|--------|--------------|-------------|-------------|
| **PR Title** | `feat: add user authentication with JWT tokens` | `fix stuff` | `good-pr-example.md` |
| **PR Description** | Detailed what/why/impact | "Fixed a bug." | `good-pr-example.md` |
| **Docstrings** | Complete Google-style with examples | None | `example-docstring-complex-function.md` |
| **README** | Updated with config, usage, examples | No changes | `example-readme-before-after.md` |
| **API Docs** | Complete with requests/responses/errors | Missing | `example-api-documentation.md` |
| **Testing** | Detailed test results and coverage | None | `good-pr-example.md` |
| **Checklist** | All items ✅ | All items ☐ | `good-pr-example.md` |

## Common Patterns from Good Example

### PR Description Structure

```markdown
## Description

[Brief summary]

### What Changed

**Core Features:**
- [List of changes]

**Documentation:**
- [List of doc updates]

**Testing:**
- [List of new tests]

### Why

[Business justification]

### Impact

**Files changed:** [number]
**Lines added:** [number]
**Breaking changes:** [yes/no]

---

## Documentation Checklist
[All items checked]

## Testing
[Detailed results]
```

### Docstring Pattern

```python
def function_name(param: type) -> return_type:
    """Brief one-line description.

    Longer description if needed explaining purpose,
    algorithm, or important details.

    Args:
        param: Description of parameter

    Returns:
        Description of return value

    Raises:
        ExceptionType: When this exception occurs

    Example:
        >>> result = function_name("test")
        >>> print(result)
        expected_output
    """
```

### README Update Pattern

```markdown
## Configuration

Create `.env` file with:

```bash
VARIABLE_NAME=value  # Description
```

## Usage

### Basic Usage

```bash
# Command with explanation
command --arg value
```

### Advanced Usage

```bash
# More complex example
command --arg1 value1 --arg2 value2
```

See [API Documentation](docs/api.md) for details.
```

## Related Documentation

- **PR Template**: `.github/PULL_REQUEST_TEMPLATE.md`
- **Playbook**: `playbooks/updating-documentation.md`
- **Knowledge Base**: `.claude/knowledge/documentation/keeping-docs-updated.md`
- **Engineering Standards**: `.claude/standards/ENGINEERING_STANDARDS.md#documentation-requirements`
- **Rule #11**: `.claude/standards/CLAUDE_CODE_RULES.md#11-documentation-updates`
- **Prompt Templates**: `prompts/documentation/`

## Tips for Using Examples

1. **Don't copy blindly** - Adapt to your specific feature
2. **Maintain the structure** - Keep the same organizational pattern
3. **Match the detail level** - Provide similar depth of explanation
4. **Include real examples** - Use actual commands, not placeholders
5. **Update as you go** - Write docs alongside code, not after

## Questions?

If you're unsure about documentation requirements:

1. **Check the checklist** in `.github/PULL_REQUEST_TEMPLATE.md`
2. **Read Rule #11** in `.claude/standards/CLAUDE_CODE_RULES.md`
3. **Follow the playbook** in `playbooks/updating-documentation.md`
4. **Compare to good example** in this directory
5. **Ask for review** before submitting PR

---

**Remember:** Documentation is NOT optional. These examples show the expected standard for all PRs.
