# Documentation Standards

> godoc conventions and documentation best practices. Use when documenting code. Use when this capability is needed.

- Skill: `tomevault-io/documentation-standards-7` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-standards-7`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-standards-7/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/documentation-standards-7

---


# Documentation Standards Skill

Go documentation conventions following godoc standards.

## When to Use

Use when writing or reviewing code documentation.

## Package Documentation

```go
// 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

```go
// 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

```go
// 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

```go
// 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

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

## README.md Structure

```markdown
# 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

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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/molcajeteai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->