What is documentation-standards?

This Claude skill provides a comprehensive framework for Go documentation, adhering to official godoc conventions and technical writing best practices. It helps developers generate high-quality package docs, function comments, and README structures to enhance code readability and project professionalism.

When should I use documentation-standards?

documentation-standards is useful in the following scenarios: • Standardizing Go package and function documentation to ensure full compatibility with godoc and pkgs.go.dev. • Generating comprehensive README.md files with consistent structures for installation, usage, and testing sections. • Improving code maintainability by providing clear, concise, and grammatically correct comments for all exported symbols. • Creating illustrative 'Example' functions within documentation to help other developers understand complex API behaviors. • Conducting documentation audits to ensure all public types and functions follow the 'explain behavior, not implementation' principle.

name	documentation-standards
description	godoc conventions and documentation best practices. Use when documenting code.

Documentation Standards Skill

Go documentation conventions following godoc standards.

When to Use

Use when writing or reviewing code documentation.

Package Documentation

// Package user provides user management functionality.
//
// This package handles user authentication, authorization,
// and profile management. It supports multiple authentication
// providers and role-based access control.
//
// Example usage:
//
//     svc := user.NewService(db)
//     user, err := svc.GetUser(ctx, userID)
//     if err != nil {
//         // handle error
//     }
//
package user

Function Documentation

// GetUser retrieves a user by ID.
//
// It returns an error if the user is not found or if
// the database connection fails.
//
// Example:
//
//     user, err := GetUser(ctx, 1)
//     if errors.Is(err, ErrNotFound) {
//         // handle not found
//     }
//
func GetUser(ctx context.Context, id int) (*User, error) {
    // implementation
}

Type Documentation

// User represents a system user with authentication details.
type User struct {
    // ID is the unique identifier for the user.
    ID int

    // Name is the user's display name.
    Name string

    // Email is the user's email address.
    // It must be unique across all users.
    Email string
}

Example Functions

// ExampleGetUser demonstrates how to retrieve a user.
func ExampleGetUser() {
    svc := NewService(db)
    user, err := svc.GetUser(context.Background(), 1)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(user.Name)
    // Output: John Doe
}

godoc Conventions

Start with symbol name - "GetUser retrieves..."
Complete sentences - Proper grammar and punctuation
No empty lines - Between comment and declaration
Explain behavior - What it does, not how
Document errors - What errors can be returned
Provide examples - For non-obvious usage

README.md Structure

# Project Name

Brief description.

## Installation

\`\`\`bash
go get github.com/user/project
\`\`\`

## Usage

\`\`\`go
package main

import "github.com/user/project"

func main() {
    // example code
}
\`\`\`

## Features

- Feature 1
- Feature 2

## Building

\`\`\`bash
make build
\`\`\`

## Testing

\`\`\`bash
make test
\`\`\`

## License

MIT

Best Practices

Document all exports - Public functions, types, constants
Be concise - Clear but brief
Use examples - For complex APIs
Keep updated - Sync with code changes
Format correctly - Follow godoc conventions
Link related items - Reference related functions
Explain non-obvious - Document "why", not "what"

documentation-standards

When & Why to Use This Skill

Use Cases