documentation-standards

Files (1)

• SKILL.md

SKILL.md (first lines)

# Documentation Standards

## README Template

Every project README should follow this structure. Omit sections that genuinely do not apply, but default to including them.

```markdown
# Project Name

[![Build Status](badge-url)][ci-link]
[![Coverage](badge-url)][coverage-link]
[![npm version](badge-url)][npm-link]
[![License](badge-url)][license-link]

One-paragraph description of what this project does, who it is for,
and why it exists. Lead with the value proposition, not the technology.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)

## Installation

### Prerequisites

- Node.js >= 18
- PostgreSQL >= 14

### Steps

npm install project-name

## Quick Start

Minimal working example — no more than 10 lines — that gets the
reader from zero to "it works."

## Usage

### Common Use Cases

Organize by task, not by API surface. Show the most common
workflows first.

### Advanced Usage

Edge cases, complex configurations, integration patterns.

## API Reference

Link to generated docs or inline the reference here.

## Configuration

| Variable        | Default   | Description                  |
|-----------------|-----------|------------------------------|
| `PORT`          | `3000`    | Server listening port        |
| `DATABASE_URL`  | —         | PostgreSQL connection string |

## Architecture

Brief overview or link to architecture docs.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE) — see LICENSE file for details.
```

### README Checklist

- [ ] Title matches the package/repo name exactly
- [ ] Description answers "what," "who," and "why" in one paragraph
- [ ] Installation steps are copy-pasteable and tested on a clean machine
- [ ] Quick Start example actually works — verify before merging
- [ ] Badges are live and point to correct URLs
- [ ] All links resolve (no 404s)
- [ ] Configuration table covers every environment variable
- [ ] License is explicitly stated and matches the LICENSE file

---

## Inline Code Comments

### When to Comment

Comment the **why**, never the **what**. If you feel the need to explain what code does, refactor the code to be self-explanatory first.

#### Good Reasons to Comment

```python
# We retry up to 3 times because the upstream API occasionally
# returns 503 during deployments (see incident #247).
for attempt in range(3):
    response = call_api()
    if response.status != 503:
        break

# Sorting by created_at DESC intentionally — the UI shows newest
# first and re-sorting client-side causes a visible flicker.
queryset = queryset.order_by("-created_at")

# HACK: The PDF library misreports page count for encrypted files.
# Remove this workaround when upstream fixes #892.
page_count = max(pdf.page_count, 1)
```

#### Bad Comments — Remove or Refactor

```python

From Claude-Code-Community-Ireland/claude-code-resources, MIT.

More from Claude-Code-Community-Ireland/claude-code-resources