Review Documentation

Review Go Documentation

Review Go package documentation from a user's perspective, identifying gaps and areas for improvement.

When to Use

Use this skill when:

• A package's public API documentation needs review
• Preparing documentation for a library release
• Evaluating whether docs are sufficient for new users

Process

1. Run go doc . to see the package overview
2. Run go doc -all . to see all exported symbols
3. Adopt the user's perspective: Imagine you're a developer who just discovered this package and wants to use it

Checklist

Review documentation against these categories:

Essential Information

• Purpose: Is the package's purpose clear in one sentence?
• Quick Start: Can a user get something working in under 5 minutes?
• Core Types: Are the 2-3 most important types clearly identified?
• Thread Safety: Is concurrency behavior documented?
• Error Handling: How do errors propagate? What error types exist?
• Lifecycle: When to create, when to close, what happens to related objects?

API Clarity

• Similar Functions: Are distinctions between similar functions clear?
  • Example: Register vs RegisterType vs DefineType
• Similar Types: Are related types differentiated?
  • Example: TypeDef vs ForeignTypeDef
• Constants: Are magic constants explained with context for when to use them?
• Unexplained Types: Does every exported type have a clear use case?

Practical Guidance

• Common Patterns: Are typical usage patterns shown?
• Anti-patterns: Are common mistakes warned against?
• Scope/Subset: If implementing a standard, what subset is covered?
• Limitations: What can't it do?

Internal vs Public

• Internal Types: Are internal-but-exported types clearly marked "do not use"?
• Stability: Is it clear which APIs are stable vs experimental?

Output Format

Provide findings in these sections:

## Critical (Users will be blocked without this)

- Issue 1
- Issue 2

## Important (Users will struggle without this)

- Issue 1
- Issue 2

## Nice to Have (Would improve experience)

- Issue 1
- Issue 2

## What's Good (Keep these)

- Strength 1
- Strength 2

Example Review

For a hypothetical database driver:

## Critical

- No mention of thread safety - can I share \*DB across goroutines?
- Close() documented but not what happens to active queries

## Important

- Query vs QueryRow vs QueryContext - when to use each?
- Error types not documented - how do I detect "connection lost"?

## Nice to Have

- Example of connection pooling configuration
- List of supported database versions

## What's Good

- Quick start example gets to working code fast
- Transaction API is well-explained with rollback semantics