Documentation

Documentation Skill

Automated documentation generation and management guidelines.

When to Apply

Use these guidelines when:

• Creating new documentation
• Updating existing docs
• Documenting APIs
• Adding inline comments
• Maintaining README files

Documentation Types

1. README Files

Every project should have a README.md with:

• Project title and description
• Installation instructions
• Usage examples
• Contributing guidelines
• License information

2. API Documentation

Document all public APIs with:

• Function signatures
• Parameter descriptions
• Return value types
• Usage examples
• Error conditions

3. Code Comments

Add comments for:

• Complex algorithms
• Non-obvious logic
• Workarounds and hacks
• TODO/FIXME items
• Performance considerations

4. Inline Documentation

Use JSDoc/Docstring style:

/**
 * Calculate the factorial of a number
 * @param {number} n - The number to calculate factorial for
 * @returns {number} The factorial of n
 * @throws {Error} If n is negative
 */
function factorial(n) {
  if (n < 0) throw new Error('Negative input');
  if (n === 0) return 1;
  return n * factorial(n - 1);
}

Documentation Standards

Style Guidelines

• Use clear, concise language
• Write in present tense
• Use active voice
• Avoid jargon when possible
• Include examples

Formatting

• Use markdown for docs
• Consistent heading levels
• Code blocks for examples
• Links to related resources
• Tables for structured data

Versioning

• Document breaking changes
• Maintain changelog
• Tag documentation versions
• Reference specific versions

Automation

Use scripts in scripts/ directory to:

• Generate API documentation
• Validate documentation coverage
• Check for outdated docs
• Format documentation

Best Practices

• Keep docs up to date with code
• Write docs for future maintainers
• Include both high-level and detailed info
• Use diagrams for complex systems
• Provide troubleshooting sections