documentation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Technical Documentation Writing

This skill guides you through creating effective technical documentation that helps users understand, use, and contribute to your software.

## When to use this skill

Use this skill when you need to:
- Write README files for projects
- Document APIs and interfaces
- Create architecture documentation
- Write inline code documentation
- Maintain project wikis or knowledge bases

## Prerequisites

- Understanding of the target audience
- Knowledge of the system being documented
- Familiarity with documentation tools (Markdown, Sphinx, Docusaurus)
- Access to code and subject matter experts

## Guidelines

### Documentation Types

**README.md** - Project entry point
- Project description and purpose
- Installation instructions
- Quick start guide
- Links to detailed documentation
- Contribution guidelines

**API Documentation** - Interface reference
- Endpoint descriptions
- Request/response examples
- Authentication details
- Error codes and handling

**Architecture Decision Records (ADRs)** - Design decisions
- Context and problem statement
- Decision drivers
- Considered options
- Decision outcome
- Consequences

**Code Comments** - Inline explanations
- Why, not what (code shows what)
- Complex algorithms
- Non-obvious behavior
- Public API documentation

### README Structure

```markdown
# Project Name

Brief description of what the project does and its main purpose.

## Features

- Core feature 1
- Core feature 2
- Core feature 3

## Installation

```bash
# Clone the repository
git clone https://github.com/user/repo.git

# Install dependencies
npm install

# Configure environment
cp .env.example .env
```

## Quick Start

```bash
# Run the application
npm start
```

Visit `http://localhost:3000` to see the application.

## Documentation

- [API Reference](docs/api.md)
- [Architecture](docs/architecture.md)
- [Contributing](CONTRIBUTING.md)

## License

[MIT](LICENSE)
```

### API Documentation

**OpenAPI/Swagger Example**
```yaml
openapi: 3.0.0
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    post:
      summary: Create a new order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customer_id, items]
              properties:
                customer_id:
                  type: integer
                  description: ID of the customer

From HelixDevelopment/agent, MIT.

More from HelixDevelopment/agent