Skip to content
Skills Library
Programming · Writing

documentation

/documentation

Guide for writing technical documentation. Use when creating README files, API documentation, guides, or inline code documentation.

Licence
MIT
Last repository change
07.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Guide for writing technical documentation. Use when creating README files, API documentation, guides, or inline code documentation.

Original author description

Guide for writing technical documentation. Use when creating README files, API documentation, guides, or inline code documentation.

How it works

  1. Anti-fabrication
  2. README Files
  3. API Documentation
  4. User Guides and Tutorials
  5. Inline Code Documentation
  6. Architecture Documentation
  7. Changelog Documentation
  8. Documentation Tools
  9. Documentation Style Guide
  10. Documentation Maintenance
Original SKILL.md headings · 354 lines, 1,433 words
SKILL.md preview
---
name: documentation
description: Guide for writing technical documentation. Use when creating README files, API documentation, guides, or inline code documentation.
---

# Technical Documentation Writing

This skill activates when writing or improving technical documentation, including README files, API documentation, user guides, and inline code documentation.

## Anti-fabrication

This skill follows `core:anti-fabrication`. Most of it is house convention — README
structure, ADR templates, changelog format, comment style — not claims that can go stale
against an upstream. The one real claim area is the "Documentation Tools" section's
generator commands (`mix docs` for ExDoc, `cargo doc` for rustdoc, Sphinx, MkDocs, JSDoc,
TypeDoc): verify the invocation against the tool's current docs before asserting it,
rather than repeating it from memory — these are stable but not immune to CLI changes.

## README Files

### Essential README Structure

Every README should cover: overview, features, installation, quick start, usage, configuration, API reference, development setup, contributing, license, acknowledgments, and support. A complete worked template with all these sections: [references/templates.md](references/templates.md).

### README Best Practices

- **Start with a clear one-liner**: Immediately tell readers what the project does
- **Include badges**: Build status, coverage, version, license
- **Show, don't tell**: Use code examples liberally
- **Keep it scannable**: Use headers, lists, and code blocks
- **Make examples runnable**: Readers should be able to copy-paste and run
- **Include visual aids**: Screenshots, diagrams, GIFs when appropriate
- **Update regularly**: Keep documentation in sync with code
- **Think about newcomers**: Write for someone seeing the project for the first time

## API Documentation

Document functions with language-native doc comments (Elixir `@doc`/`@spec`, JSDoc, Python docstrings, Rust doc comments), document modules/classes with their purpose and public API, and document REST endpoints with method, auth, request/response bodies, and error responses. Worked examples for all three: [references/api-documentation.md](references/api-documentation.md).

## User Guides and Tutorials

### Tutorial Structure

```markdown
# Tutorial: Building Your First [Feature]

## What You'll Build

Brief description of the end result.

## Prerequisites

- Knowledge requirement 1
- Installed tool 1
- Account/access requirement

## Step 1: [First Major Step]

Explanation of what we're doing and why.

```language
// Code for this step
```

**What's happening here:**
- Explanation of key line 1
- Explanation of key line 2

## Step 2: [Next Step]

Continue with incremental steps...

## Testing

How to verify it works.

## Next Steps

- Related tutorial 1
- Advanced topic 1
- Further reading
```

### Tutorial Best Practices

- **Show working code first**: Let readers see the goal before diving into details
- **Explain the 'why'**: Don't just show what to do, explain reasoning
- **Incremental steps**: Each step should build on the previous
- **Include checkpoints**: Ways to verify progress
- **Provide complete code**: Include a repository or final code snippet
- **Anticipate problems**: Address common mistakes
- **Link to references**: Point to relevant API docs and resources

## Inline Code Documentation

### When to Write Comments

**DO write comments for:**
- Complex algorithms or business logic
- Non-obvious decisions ("why" not "what")
- Workarounds for bugs or limitations
- Public APIs and exported functions
- Configuration and constants

**DON'T write comments for:**
- Obvious code
- What the code does (prefer clear naming)
- Outdated information
- Commented-out code (use version control)

### Good Comment Examples

```elixir
# Good: Explains WHY
# Use exponential backoff to avoid overwhelming the API after rate limit errors
defp retry_with_backoff(attempt) do
  :timer.sleep(:math.pow(2, attempt) * 1000)
end

# Bad: Explains WHAT (obvious from code)
# Multiply 2 to the power of attempt and multiply by 1000
defp retry_with_backoff(attempt) do
  :timer.sleep(:math.pow(2, attempt) * 1000)
end

# Good: Documents workaround
# NOTE: Using String.to_existing_atom because the Erlang VM limits atoms to ~1M.
# All valid status atoms are pre-defined in this module.
def parse_status(status_string) do
  String.to_existing_atom(status_string)
end

# Good: Explains business rule
# Users must be at least 13 years old per COPPA regulations
@minimum_age 13
```

## Architecture Documentation

### Architecture Decision Records (ADR)

Document significant architectural decisions:

```markdown
# ADR 001: Use PostgreSQL for Primary Database

## Status

Accepted

## Context

We need to choose a database for our application that supports:
- ACID transactions
- Complex queries with joins
- JSON data storage
- Full-text search
- Horizontal scalability (future requirement)

## Decision

We will use PostgreSQL as our primary database.

## Consequences

### Positive

- Mature, stable, well-documented
- Excellent JSON support with JSONB
- Built-in full-text search
- Strong consistency guarantees
- Large ecosystem of tools and extensions
- Can scale with read replicas and partitioning

### Negative

- More complex to operate than simpler databases
- Vertical scaling has limits (though sufficient for our needs)
- Requires more server resources than lighter alternatives

### Neutral

- Team needs to learn PostgreSQL-specific features
- May need to hire PostgreSQL expertise as we scale

## Alternatives Considered

- **MySQL**: Weaker JSON support, less feature-rich
- **MongoDB**: No ACID guarantees, eventual consistency issues
- **SQLite**: Not suitable for multi-user web applications
```

## Changelog Documentation

Follow Keep a Changelog format:

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New feature in development

## [1.2.0] - 2024-01-15

### Added
- User profile pictures
- Email notification preferences
- Dark mode support

### Changed
- Improved search performance by 40%
- Updated UI to match new brand guidelines

### Fixed
- Login redirect loop on Safari
- Memory leak in background sync process

### Deprecated
- Old `/v1/users` endpoint (use `/v2/users` instead)

## [1.1.0] - 2024-01-01

### Added
- Two-factor authentication
- Export user data to JSON

### Security
- Fixed XSS vulnerability in comment rendering

## [1.0.0] - 2023-12-15

### Added
- Initial release
- User registration and authentication
- Basic user profiles
```

## Documentation Tools

### Documentation Generators

- **Elixir**: ExDoc - `mix docs`
- **JavaScript**: JSDoc, TypeDoc
- **Python**: Sphinx, MkDocs
- **Rust**: rustdoc - `cargo doc`
- **Static sites**: VitePress, Docusaurus, GitBook

### Prose Linting

- **Vale**: `mise run test:prose` — checks banned words, clutter, sentence length, and hedged directives. See `/vale:vale` for the tool and `/core:technical-english` for the register rules it enforces.

### Diagram Tools

- **Mermaid**: Diagrams in Markdown
  ```markdown
  ```mermaid
  graph TD
      A[User] -->|Requests| B[Load Balancer]
      B --> C[Web Server 1]
      B --> D[Web Server 2]
      C --> E[Database]
      D --> E
  ```
  ```

- **PlantUML**: UML diagrams as code
- **Excalidraw**: Hand-drawn style diagrams
- **Draw.io**: Flowcharts and diagrams

## Documentation Style Guide

### Writing Style

- **Use active voice**: "The function returns" not "The value is returned"
- **Be concise**: Remove unnecessary words
- **Use present tense**: "Returns" not "Will return"
- **Be specific**: "Timeout in milliseconds" not "Timeout value"
- **Avoid jargon**: Or explain it when necessary
- **Use examples**: Show, don't just tell

### Formatting Conventions

- **Code**: Use `backticks` for inline code
- **Commands**: Show with `$` prefix or in code blocks
- **File paths**: Use `code formatting`
- **Emphasis**: Use **bold** for important points, *italic* for slight emphasis
- **Lists**: Use bullets for unordered, numbers for sequential steps
- **Headers**: Use sentence case, not title case

### Code Examples

- **Complete**: Include all necessary imports and setup
- **Runnable**: Readers should be able to copy and run
- **Realistic**: Use meaningful variable names and realistic data
- **Commented**: Explain non-obvious parts
- **Tested**: Ensure examples actually work
- **Current**: Keep in sync with latest API

## Documentation Maintenance

### Keeping Docs Updated

- Update documentation in the same PR as code changes
- Review docs during code review
- Set up doc linting (broken links, outdated examples)
- Schedule regular documentation audits
- Use version tags in examples when API changes
- Mark deprecated features clearly

### Documentation Testing

```elixir
# Elixir doctests - examples in docs are actual tests
defmodule Math do
  @doc """
  Adds two numbers.

  ## Examples

      iex> Math.add(2, 3)
      5

  """
  def add(a, b), do: a + b
end
```

```rust
/// Adds two numbers.
///
/// # Examples
///
/// ```
/// assert_eq!(add(2, 3), 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}
```

## Key Principles

- **Write for your audience**: Tailor complexity to reader's experience level
- **Show examples**: Code examples are worth a thousand words
- **Keep it current**: Outdated docs are worse than no docs
- **Make it scannable**: Use headers, lists, code blocks, and white space
- **Explain the 'why'**: Help readers understand reasoning, not just steps
- **Start simple**: Begin with quickstart, then go deeper
- **Test documentation**: Ensure examples run and links work
- **Iterate based on feedback**: Improve based on user questions and confusion
Files in this package (3)
  • SKILL.md 10 KB
  • references/api-documentation.md 3 KB
  • references/templates.md 2 KB

Versions

RepositoryScoreLicence
This page · vinnie357/claude-skills100MIT
software-combined/SC_AI100Apache-2.0
DaveSkender/Stock.Indicators100Apache-2.0
mcouthon/agents100MIT
YLfjuk/deltafold100MIT
comet-ml/opik100Apache-2.0
runwield/runwield100MIT
anthropics/knowledge-work-plugins100Apache-2.0
luocfprime/labtasker100Apache-2.0

Database snapshot: 13.11.2026 · package version aea6f439446e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100code-documentation
    Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
  • 100documentation-generator
    Automatically generate documentation when user mentions needing API docs, README files, user guides, developer guides, or changelogs. Analyzes code and generates appropriate documentation based on context. Invoke when user mentions "document", "docs", "README", "API…
  • 100code-documentation
    Automatically generate clear, comprehensive documentation for codebases — including API references, inline docstrings, README files, and usage guides. Use when the user requests code documentation or provides relevant inputs for this workflow.
  • 100documentation-guide
    Guide documentation structure, content requirements, and project documentation best practices. Use when: creating README, documentation, docs folder, project setup, technical docs. Not for: generating docs mechanically from source — use /docgen; changelog entries — use…
  • 100documentation-standards
    This skill should be used when the user asks to "write documentation", "create docs", "document code", "improve documentation", "documentation best practices", "diataxis", "technical writing", "API documentation", "user guide", mentions documentation quality, documentation…
  • 100documentation-patterns
    Technical documentation patterns for READMEs, ADRs, API docs (OpenAPI 3.1), changelogs, and writing style guides. Use when creating project documentation, writing architecture decisions, documenting APIs, or maintaining changelogs.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.