# 046 Never 99796521

> Writing project documentation

- Skill: `tools-only/046-never-99796521` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/046-never-99796521`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/046-never-99796521/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/046-never-99796521

---

# Writing project documentation

Never generate documentation which simply restates the entity's name. Describe **why, not just what**.

Inspect the data before writing documentation about it, using discovering-data.

## Table level

Describe the grain of the table, its purpose and any edge cases

Bad:

```yml
models:
  - name: active_customers
    description: All customers who are active
```

Good: 

```yml
models:
  - name: active_customers
    description: The `customers` table pre-filtered for easier analytics. One row per customer whose contract_expiry_date is null or in the future
```

## Column level

Calculated fields should include a brief description of the transformation and its purpose.

Bad:

```yml
models: 
  - name: customers
    columns: 
      - name: customer_id
        description: The customer's identification number
```

Good:

```yml
models: 
  - name: customers
    columns: 
      - name: customer_id
        description: Users older than 2020-02-16 have `v1_` prefixed to their customer ID due to the platform migration.
```