Generate Summary Documentation

Generate well-organized, digestible documentation summaries in markdown format. This skill helps you create structured documentation that makes complex topics easy to understand.

Documentation Structure

All documentation is stored in a .summary/ directory with this structure:

.summary/
├── README.md                    # Main table of contents
├── topic-name/                  # Topic-specific folder
│   ├── overview.md              # High-level summary
│   ├── key-concepts.md          # Core concepts explained
│   ├── syntax-reference.md      # Special syntax and patterns
│   ├── how-it-works.md          # Implementation details
│   └── examples.md              # Practical examples
└── another-topic/
    └── ...

Documentation Workflow

Step 1: Analyze the Content

Before generating documentation:

Identify the main topic and subtopics
Determine what type of content you're documenting (library, API, infrastructure, codebase)
Gather relevant information from code, files, or user input

Step 2: Create Directory Structure

Check if .summary/ exists at the workspace root
Create a topic-specific subdirectory with a clear, kebab-case name
Plan the file split based on content volume

Step 3: Generate Documentation Files

Create markdown files for each section of the topic. Each file should be focused and digestible (aim for 100-300 lines per file).

Required Sections

overview.md - High-level summary

# [Topic Name] - Overview

## Summary
Brief 2-3 paragraph summary of what this is and why it matters.

## Key Points
- Point 1: Important aspect
- Point 2: Critical feature
- Point 3: Notable characteristic

## Quick Links
- [Key Concepts](key-concepts.md)
- [Syntax Reference](syntax-reference.md)
- [How It Works](how-it-works.md)

key-concepts.md - Core concepts explained

# [Topic Name] - Key Concepts

## Concept 1: [Name]
Brief explanation of the concept.

### Details
- Detailed point 1
- Detailed point 2

### When to Use
Practical guidance on when this concept applies.

---

## Concept 2: [Name]
...

syntax-reference.md - Special syntax and patterns (if applicable)

# [Topic Name] - Syntax Reference

## Basic Syntax

### Pattern 1
\`\`\`language
code example
\`\`\`

**Explanation**: What this does and when to use it.

### Pattern 2
...

## Special Cases
Document any edge cases or special syntax variations.

how-it-works.md - Implementation details and internals

# [Topic Name] - How It Works

## Architecture
Explain the overall architecture or flow.

## Step-by-Step Process
1. **Step 1**: What happens first
2. **Step 2**: What happens next
3. **Step 3**: Final result

## Under the Hood
Technical details about implementation.

## Gotchas and Considerations
- Gotcha 1: What to watch out for
- Gotcha 2: Common mistake to avoid

examples.md - Practical examples

# [Topic Name] - Examples

## Example 1: [Use Case]
**Scenario**: Describe the use case

\`\`\`language
code example
\`\`\`

**Explanation**: What this example demonstrates.

---

## Example 2: [Use Case]
...

Optional Sections

Create additional files as needed:

advanced-usage.md - Advanced patterns and techniques
troubleshooting.md - Common issues and solutions
comparison.md - Comparisons with alternatives
migration.md - Migration guides
best-practices.md - Recommended patterns

Step 4: Update Main README

After creating topic documentation, update .summary/README.md:

# Documentation Summary

This directory contains structured, digestible documentation summaries.

## Topics

### [Topic Name 1](topic-name-1/)
Brief one-line description of this topic.

**Contents:**
- [Overview](topic-name-1/overview.md) - High-level summary
- [Key Concepts](topic-name-1/key-concepts.md) - Core concepts
- [Syntax Reference](topic-name-1/syntax-reference.md) - Special syntax
- [How It Works](topic-name-1/how-it-works.md) - Implementation details
- [Examples](topic-name-1/examples.md) - Practical examples

---

### [Topic Name 2](topic-name-2/)
Brief one-line description of this topic.

**Contents:**
...

File Organization Guidelines

When to Split Files

Split content into multiple files when:

A single file would exceed 300 lines
The topic has distinct subtopics that deserve separate focus
Different audience levels (beginner vs advanced)

Example: Large library documentation

library-name/
├── overview.md
├── getting-started.md       # Split from overview
├── core-concepts.md
├── api-authentication.md    # Split from syntax
├── api-endpoints.md         # Split from syntax
├── data-models.md          # Split from how-it-works
├── error-handling.md       # Split from how-it-works
└── examples/               # Subdirectory for many examples
    ├── basic-usage.md
    ├── advanced-patterns.md
    └── real-world-scenarios.md

Naming Conventions

Folders: Use kebab-case, descriptive names (e.g., terraform-modules, api-gateway)
Files: Use kebab-case, clear purpose (e.g., getting-started.md, api-reference.md)
Headers: Use sentence case in markdown headings

Cross-Referencing

Use relative links to connect related documentation:

For more details on authentication, see [API Authentication](api-authentication.md).

Related topics:
- [Error Handling](error-handling.md)
- [Data Models](data-models.md)

Content Writing Guidelines

1. Use Clear, Concise Language

Write for human understanding:

✅ "This function validates user input before processing"
❌ "This function implements a validation paradigm that encompasses..."

2. Structure with Headers

Use hierarchical headers for easy scanning:

# Main Topic

## Major Section

### Subsection

#### Detail Point

3. Include Code Examples

Always show practical examples with explanations:

### Example: User Authentication

\`\`\`python
@app.route('/login', methods=['POST'])
def login():
    username = request.json.get('username')
    password = request.json.get('password')
    
    if authenticate_user(username, password):
        return jsonify({'token': generate_token(username)})
    return jsonify({'error': 'Invalid credentials'}), 401
\`\`\`

**Key Points:**
- The `authenticate_user()` function validates credentials
- Successful login returns a JWT token
- Failed attempts return 401 status code

4. Highlight Important Information

Use blockquotes for important notes:

> **Important**: Always validate user input before processing to prevent security vulnerabilities.

> **Note**: This feature requires version 2.0 or higher.

5. Use Lists Effectively

Use bullet points for unordered information
Use numbered lists for sequential steps
Keep list items parallel in structure

6. Add Visual Breaks

Use horizontal rules to separate major sections:

## Section 1
Content...

---

## Section 2
Content...

Update Strategy

When updating existing documentation:

Read existing files first - Check what's already documented
Identify gaps - What's missing or outdated?
Update incrementally - Don't regenerate everything; update specific files
Maintain consistency - Match existing style and structure
Update the main README - Ensure table of contents is current

Special Considerations

For Infrastructure Documentation

When documenting infrastructure:

Include architecture diagrams (mermaid or references)
Document dependencies and prerequisites
Explain resource relationships
Include deployment procedures

For API Documentation

When documenting APIs:

List all endpoints with methods
Show request/response examples
Document authentication requirements
Include error codes and meanings

For Library/Framework Documentation

When documenting libraries:

Show installation steps
Provide quick start guide
Document all public APIs
Include configuration options

For Codebase Documentation

When documenting codebases:

Explain directory structure
Document architectural patterns
Show data flow
List key modules and their purposes

Complete Example

Here's a complete example for documenting a fictional API:

User Request: "Summarize our payment processing API"

Your Response:

Create directory structure:

.summary/
└── payment-api/
    ├── overview.md
    ├── authentication.md
    ├── endpoints.md
    ├── data-models.md
    ├── error-handling.md
    └── examples.md

Generate each file with appropriate content
Update .summary/README.md with the new topic
Verify all cross-references work

Quality Checklist

Before completing the documentation:

All required sections are present
Files are appropriately sized (100-300 lines)
Code examples are included and explained
Cross-references use correct relative paths
Main README.md is updated
Consistent formatting throughout
Topic folder name is clear and descriptive
No duplicate information across files

Tips for Success

Start with overview.md - This helps organize your thoughts
Write for the reader - Assume they're learning this for the first time
Use examples liberally - Concrete examples beat abstract explanations
Keep it current - Documentation should reflect the actual implementation
Make it scannable - Use headers, lists, and code blocks effectively

When the user asks you to summarize or document something, follow this workflow to create organized, digestible documentation in the .summary/ directory.

generate-summary-docs