Documentation Standards Skill

Provide expert guidance on creating effective, maintainable technical documentation.

When to Apply

Activate when the user:

• Asks about documentation best practices
• Needs to document code, APIs, or features
• Wants to improve existing documentation
• Asks about JSDoc, docstrings, or comments
• Discusses README writing or user guides

Documentation Hierarchy

Project Documentation
├── README.md                    # First impression, quick start
├── CONTRIBUTING.md              # How to contribute
├── CHANGELOG.md                 # Version history
├── docs/
│   ├── getting-started.md       # Onboarding guide
│   ├── user-guide.md            # End-user documentation
│   ├── api-reference.md         # API documentation
│   └── architecture.md          # Technical deep-dive
└── In-code documentation        # Context-specific docs

In-Code Documentation

Principles

1. Document why, not what: Code shows what, comments explain why
2. Keep it current: Outdated docs are worse than no docs
3. Use standard formats: JSDoc, docstrings, GoDoc

JavaScript/TypeScript (JSDoc)

/**
 * Authenticates a user and creates a session.
 *
 * This function validates credentials against the database and,
 * if successful, creates a new session token with the configured
 * expiration time.
 *
 * @param email - The user's email address
 * @param password - The user's password (will be hashed for comparison)
 * @returns A promise resolving to the authentication result
 * @throws {AuthenticationError} When credentials are invalid
 * @throws {RateLimitError} When too many attempts have been made
 *
 * @example
 * ```typescript
 * try {
 *   const result = await authenticate('user@example.com', 'password');
 *   if (result.success) {
 *     setSession(result.token);
 *   }
 * } catch (error) {
 *   handleAuthError(error);
 * }
 * ```
 */
export async function authenticate(
  email: string,
  password: string
): Promise<AuthResult> {

Python (Docstrings)

def authenticate(email: str, password: str) -> AuthResult:
    """
    Authenticate a user and create a session.

    This function validates credentials against the database and,
    if successful, creates a new session token with the configured
    expiration time.

    Args:
        email: The user's email address.
        password: The user's password (will be hashed for comparison).

    Returns:
        AuthResult containing:
            - success: Whether authentication succeeded
            - token: Session token (if successful)
            - user: User data (if successful)

    Raises:
        AuthenticationError: When credentials are invalid.
        RateLimitError: When too many attempts have been made.

    Example:
        >>> result = authenticate('user@example.com', 'password')
        >>> if result.success:
        ...     set_session(result.token)
    """

Go (GoDoc)

// Authenticate verifies user credentials and creates a session.
//
// This function validates credentials against the database and,
// if successful, creates a new session token with the configured
// expiration time.
//
// Parameters:
//   - email: The user's email address
//   - password: The user's password (will be hashed for comparison)
//
// Returns an AuthResult and an error. Possible errors:
//   - AuthenticationError: credentials are invalid
//   - RateLimitError: too many attempts
//
// Example:
//
//	result, err := Authenticate("user@example.com", "password")
//	if err != nil {
//	    return handleError(err)
//	}
//	if result.Success {
//	    SetSession(result.Token)
//	}
func Authenticate(email, password string) (*AuthResult, error) {

API Documentation

OpenAPI/Swagger Format

/users/{id}:
  get:
    summary: Get user by ID
    description: |
      Retrieves a single user by their unique identifier.
      Returns 404 if the user doesn't exist.
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The unique user identifier
    responses:
      '200':
        description: User found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            example:
              id: "123e4567-e89b-12d3-a456-426614174000"
              name: "John Doe"
              email: "john@example.com"
      '404':
        description: User not found

API Documentation Structure

1. Endpoint overview: What it does
2. Request format: Parameters, body, headers
3. Response format: Status codes, body structure
4. Examples: Request and response examples
5. Errors: Possible error conditions

README Structure

Essential Sections

# Project Name

Brief description (1-2 sentences).

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

Step-by-step installation instructions.

## Quick Start

Minimal code example to get started.

## Usage

More detailed usage examples.

## Configuration

Configuration options and environment variables.

## Contributing

Link to CONTRIBUTING.md or brief guidelines.

## License

License information.

README Best Practices

1. Lead with what the project does
2. Show, don't tell (use examples)
3. Keep it scannable (use headings, lists)
4. Include a quick start (< 5 steps)
5. Link to detailed docs for more info

User Guide Structure

Sections

1. Introduction: What, why, who
2. Getting Started: Prerequisites, installation, first steps
3. How-To Guides: Task-oriented tutorials
4. Reference: Complete feature reference
5. Troubleshooting: Common issues and solutions
6. FAQ: Frequently asked questions

Writing Style

• Use active voice
• Address the reader as "you"
• Use present tense
• Keep sentences short
• Include examples for every concept

Documentation Anti-Patterns

Avoid

1. Documenting obvious code: i++ // increment i
2. Stale documentation: Update docs with code changes
3. Verbose explanations: Be concise
4. Missing examples: Show, don't just tell
5. Jargon without explanation: Define terms
6. Assumptions about knowledge: Be explicit

Comments vs Documentation

Use Comments For

• Non-obvious logic explanations
• Performance considerations
• Security implications
• Workarounds with context
• TODOs with context

Don't Use Comments For

• Explaining what code does (make code self-documenting)
• Version control history (use git)
• Commented-out code (delete it)
• Obvious operations

Changelog Format

Keep a Changelog Standard

# Changelog

## [1.2.0] - 2025-01-15

### Added
- User authentication with OAuth support
- Password reset functionality

### Changed
- Improved login form validation
- Updated session timeout to 30 minutes

### Fixed
- Fixed memory leak in session management
- Corrected validation error messages

### Security
- Implemented CSRF protection

## [1.1.0] - 2025-01-01
...

Applying This Skill

When helping with documentation:

1. Identify the documentation type needed
2. Apply the appropriate format/structure
3. Use the project's existing conventions
4. Provide concrete examples
5. Keep it maintainable and current