reference-docs

リファレンスドキュメントのパターン

リファレンスドキュメントは情報を中心とし、経験豊富なユーザーが正確な技術情報をすばやく見つけられるようにします。このスキルでは、明確で一覧しやすいリファレンスページを作成するためのパターンを紹介します。

依存関係： 基本的な執筆原則については、必ずこのスキルと docs-style を併用してください。チュートリアル、ハウツー、解説ではなくリファレンスが適切な形式かどうかを確認するには、docs-style/references/diataxis-compass.md を参照してください。

目的と対象読者

• 対象者： 特定の情報を探している経験豊富なユーザー
• 目標： 技術的な詳細をすばやく参照できること
• 用途： 学習ではなく、情報の参照
• 期待事項： 簡潔さ、一貫性、完全性

ドキュメント構成テンプレート

リファレンスドキュメントを作成する際は、次のテンプレートを使用してください。

---
title: "[Symbol/API Name]"
description: "One-line description of what it does"
---

# [Name]

Brief description (1-2 sentences). State what it is and its primary purpose.

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `param1` | `string` | Yes | What this parameter controls |
| `param2` | `number` | No | Optional behavior modification. Default: `10` |

## Returns

| Type | Description |
|------|-------------|
| `ReturnType` | What the function returns and when |

## Example

```language
import { symbolName } from 'package';

// Complete, runnable example showing common use case
const result = symbolName({
  param1: 'realistic-value',
  param2: 42
});

console.log(result);
// Expected output: { ... }

関連項目

• RelatedSymbol - 簡単な説明
• AnotherSymbol - 簡単な説明

## Writing Principles

### Describe, and Only Describe

Reference is austere, neutral, and authoritative — a map the reader can trust without independent verification. Its one job is to describe the machinery: commands, options, parameters, return values, limits, warnings. It does not instruct (that's How-To), teach (Tutorial), or argue (Explanation). When you feel the urge to explain *why* or walk the reader through a task, link out instead of inlining it; a digression interrupts and obscures the facts the reader came to consult.

### Structure Mirrors the Product

> "The structure of the documentation should mirror the structure of the product."

Organise reference so a reader can navigate the code and the docs in parallel — one reference entry per module, class, endpoint, or command, in the product's own order. Don't impose a narrative or thematic structure the product doesn't have; consistency of placement is what makes reference fast to consult.

### Brevity Over Explanation

- State facts, not rationale
- Avoid "why" - save that for Explanation docs
- Cut unnecessary words

**Do:**
```markdown
Returns the user's display name.

避けること：

This function is useful when you need to get the user's display name
because it handles all the edge cases for you automatically.

文章ではなく、一覧しやすい表を使う

推奨：

| Name | Type | Description |
|------|------|-------------|
| `userId` | `string` | Unique user identifier |
| `options` | `Options` | Configuration object |

非推奨：

The first parameter is `userId`, which should be a string containing
the unique user identifier. The second parameter is `options`, which
is an Options object containing the configuration.

項目間で形式を統一する

類似項目のリファレンスページは、すべて同じ構成にしてください。

• 見出しの順序を統一する
• 表の列を統一する
• コード例の形式を統一する
• 関連リンクのセクションを統一する

すべての例を実行可能にする

• すべてのインポートを含める
• 完全で動作するコードを示す
• 現実的な値を使う（「foo」「bar」「test123」などは使わない）
• 役立つ場合は期待される出力を含める

コード例のパターン

よくあるユースケースを最初に示す

## Example

### Basic Usage

```typescript
const user = await getUser('user-123');
console.log(user.name);

オプションを指定する場合

const user = await getUser('user-123', {
  includeMetadata: true,
  fields: ['name', 'email', 'role']
});

### Include Setup and Context

```markdown
```typescript
import { Client } from '@example/sdk';

// Initialize client (required once per application)
const client = new Client({ apiKey: process.env.API_KEY });

// Now use the function
const result = await client.users.list();

### Use Realistic Values

**Do:** `userId: 'usr_a1b2c3d4'`
**Avoid:** `userId: 'foo'`

**Do:** `email: '[email protected]'`
**Avoid:** `email: '[email protected]'`

## Parameter Documentation Patterns

### Required vs Optional

Clearly indicate which parameters are required:

```markdown
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | - | Your API key |
| `timeout` | `number` | No | `30000` | Request timeout in ms |
| `retries` | `number` | No | `3` | Number of retry attempts |

複雑な型

オブジェクト型のパラメーターでは、構造を記述してください。

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `options` | `UserOptions` | No | Configuration options |

### UserOptions

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `includeDeleted` | `boolean` | No | Include soft-deleted users |
| `fields` | `string[]` | No | Fields to return |
| `limit` | `number` | No | Maximum results (default: 100) |

列挙値

使用できる値を明確に記述してください。

| Name | Type | Values | Description |
|------|------|--------|-------------|
| `status` | `string` | `active`, `pending`, `suspended` | User account status |

戻り値のドキュメント

単純な戻り値

## Returns

`User` - The requested user object, or `null` if not found.

複雑な戻り値

## Returns

| Property | Type | Description |
|----------|------|-------------|
| `data` | `User[]` | Array of user objects |
| `pagination` | `Pagination` | Pagination metadata |
| `total` | `number` | Total matching records |

エラー条件

## Errors

| Error | Condition |
|-------|-----------|
| `NotFoundError` | User does not exist |
| `UnauthorizedError` | Invalid or expired API key |
| `RateLimitError` | Too many requests |

API リファレンスの詳細

HTTP エンドポイント

## Endpoint

```http
GET /api/v1/users/{userId}

パスパラメーター

名前	型	説明
userId	string	ユーザーを一意に識別する ID

クエリパラメーター

名前	型	必須	説明
fields	string	いいえ	フィールドをカンマ区切りで指定したリスト

ヘッダー

名前	必須	説明
Authorization	はい	ベアラートークン
X-Request-ID	いいえ	リクエストの追跡 ID

レスポンス

{
  "id": "usr_a1b2c3d4",
  "name": "Jane Smith",
  "email": "[email protected]"
}

## Component/Props Reference

For UI components:

```markdown
## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary'` | `'primary'` | Visual style |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
| `disabled` | `boolean` | `false` | Disable interactions |
| `onClick` | `() => void` | - | Click handler |

## Slots

| Name | Description |
|------|-------------|
| `default` | Button content |
| `icon` | Icon to display before text |

関連リンクのセクション

関連するコンテンツへのリンクを必ず含めてください。

## Related

- [createUser](/reference/create-user) - Create a new user
- [updateUser](/reference/update-user) - Modify user properties
- [deleteUser](/reference/delete-user) - Remove a user
- [User Authentication Guide](/guides/authentication) - How authentication works

ゲート（完了までの順序）

リファレンスページを完成とみなす前に、次の順序付きワークフローを実施してください。ステップ n を終えてから n+1 に進みます。各ステップには、作成したページだけを見て確認できる合格条件があります（「内部で確認しました」は不可）。

1. 構成 — セクションがプロジェクトのテンプレートに合っていること（通常は Parameters、Returns、Example、Related。HTTP ドキュメントでは Endpoint、Path/Query、Headers、Response も追加）。合格条件： 必須セクションがすべて存在するか、欠落するセクションについての一行の注記が Related の下にあること（例：「クエリパラメーターはありません」）。
2. 表 — Parameters／returns／errors には、項目間で形式を統一するおよび必須と任意の区別に従い、列を統一した表を使用すること。合格条件： Description セルが空欄でなく、リリース済み API に TBD や ??? がないこと。
3. 実行可能な例 — 少なくとも1つの例が、すべての例を実行可能にするおよび現実的な値を使うという要件を満たしていること。合格条件： インポートが含まれ、ユーザーに表示される文字列が現実的であること（API の説明だけを目的とする例を除き、汎用的な foo／bar は使用しない）。
4. 関連項目 — 合格条件： ## Related に、別のリファレンスまたはガイドへの Markdown リンクが1つ以上含まれているか、関連するシンボルがないことを明示する文が1つ含まれていること。

リファレンスページのチェックリスト

上記の**ゲート（完了順）**の後に、次の項目を確認します。

• タイトルがシンボル／API 名と完全に一致している
• 説明が明確な一文になっている
• すべてのパラメーターが型とともに記載されている
• 必須か任意かが明確に示されている
• 任意のパラメーターにはデフォルト値が指定されている
• 戻り値の型と構造が記載されている
• 完全で実行可能な例が少なくとも 1 つある
• 例に現実的な値が使われている
• 関連ページにリンクしている
• ドキュメント内の他のリファレンスページと形式が一致している

リファレンスと他のドキュメントタイプの使い分け

ユーザーの目的	ドキュメントタイプ	例
「学びたい」	チュートリアル	「初めての統合を構築する」
「X を実行したい」	ハウツー	「SSO の設定方法」
「理解したい」	解説	「キャッシュの仕組み」
「Y を調べたい」	リファレンス	「API エンドポイントのリファレンス」

リファレンスと解説は、認知を目的とする 2 つのタイプであり、混同されやすいものです。リファレンスは作業中に参照する中立的な事実を「提示」し、解説は考察しながら読むための理由や背景を「論じ」ます。コンパスの手順と違いについて詳しくは、docs-style/references/diataxis-compass.md を参照してください。

関連スキル

• docs-style：基本的な執筆規則と構成要素
• Diataxis compass：タイプの選択、2×2 のマップ、品質モデル
• tutorial-docs：学習を目的としたコンテンツのチュートリアルパターン
• howto-docs：タスクを目的としたコンテンツのハウツーガイドパターン
• explanation-docs：概念的なドキュメントのパターン