docs-style

ドキュメントのスタイルガイド

人間の読者にも LLM にも分かりやすく、一貫性があり、利用しやすいドキュメントにするため、ドキュメントを作成またはレビューする際は、以下の原則を適用してください。

まず適切なドキュメントの種類を選ぶ

スタイルは目的に役立つものであり、その目的は、執筆するドキュメントが Diataxis の4つの種類のどれに当たるかによって異なります。以下の規則を適用する前に、そのドキュメントがチュートリアル（学習）、ハウツーガイド（タスクの実行）、リファレンス（情報の参照）、解説（理解）のどれに当たるかを決めてください。これらは互換性がなく、1つのドキュメントに混在させると、どの種類の効果も損なわれます。

選ぶときは、2つの指針となる質問を考えてください。行動か認知か？習得か応用か？

読者の姿勢	種類
「学習中です。手順を示してください」	チュートリアル
「達成したい目標があります。そこまで導いてください」	ハウツーガイド
「作業中です。情報を参照させてください」	リファレンス
「じっくり考えています。理由を理解できるようにしてください」	解説

判断手順全体、2×2のマップ、曖昧さの大半を解消する2つの区別（チュートリアルとハウツーガイド、リファレンスと解説）、および品質モデルについては、references/diataxis-compass.mdを参照してください。種類を選んだら、このガイドの原則を基に、種類ごとのスキル（tutorial-docs、howto-docs、reference-docs、explanation-docs）を活用できます。

文体とトーン

二人称を使う

「ユーザー」や「開発者」ではなく、「あなた」として読者に直接呼びかけます。

You can configure the API by setting environment variables.


The user can configure the API by setting environment variables.
Developers should configure the API by setting environment variables.

能動態を優先する

主語が動作を行う文を書きます。能動態は明確で、簡潔です。

Create a configuration file in the root directory.
The function returns an array of user objects.


A configuration file should be created in the root directory.
An array of user objects is returned by the function.

簡潔にする

不要な言葉を削ります。すべての言葉に役割を持たせてください。

Run the install command.


In order to proceed, you will need to run the install command.

This endpoint returns user data.


This endpoint is used for the purpose of returning user data.

簡潔にできるよくある表現：

次の表現の代わりに	次を使う
〜するために	〜する
〜を目的として	〜する、〜のために
〜の場合には	〜の場合
現時点では	現在
〜という事実により	〜のため
〜する必要がある	〜してください
〜することができる	〜できる
〜を利用する	〜を使う

ドキュメントの構成

明確で内容が分かる見出しを書く

見出しを見れば、セクションの内容が正確に分かるようにします。気の利いた表現や曖昧なタイトルは避けてください。

## Install the CLI
## Configure Authentication
## Handle Rate Limits


## Getting Started (vague)
## The Fun Part (clever)
## Misc (uninformative)

ページ単体で完結させる

読者が検索結果からどのページにも直接アクセスする可能性があることを想定します。各ページでは、次の点を説明してください。

• 機能や概念が何か
• 前提条件を明確に示す
• トピックを理解するために必要な背景をすべて示す

# Webhooks

Webhooks let you receive real-time notifications when events occur in your account.

## Prerequisites

- An active API key with webhook permissions
- A publicly accessible HTTPS endpoint

## Create a Webhook

...

意味に合ったマークアップを使う

コンテンツの種類に適した形式を選びます。

• 見出し：適切な階層に従う（h1 > h2 > h3。階層を飛ばさない）
• リスト：関連する項目が複数ある場合に使う
• 表：属性が一貫した構造化データに使う
• コードブロック：コード、コマンド、ファイルパスを記載する場合に使う

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| api_key | string | Yes | Your API key |
| timeout | integer | No | Request timeout in seconds |


To authenticate, you can:
- Use an API key in the header
- Use OAuth 2.0
- Use a service account

内容をざっと把握しやすくする

長い段落は、読みやすいまとまりに分けます。

• 段落は最大3〜4文にする
• 項目の列挙には箇条書きを使う
• 長いセクションには小見出しを追加する
• 重要な情報を先に示す（逆ピラミッド型）

## Error Handling

The API returns standard HTTP status codes.

### Common Errors

- **400 Bad Request**: Invalid parameters. Check the request body.
- **401 Unauthorized**: Invalid or missing API key.
- **429 Too Many Requests**: Rate limit exceeded. Wait and retry.

### Retry Strategy

For 429 errors, use exponential backoff starting at 1 second.

一貫性

1つの概念には1つの用語を使う

用語を1つ選び、一貫して使います。用語を切り替えると読者が混乱します。

Generate an API key in the dashboard. Use your API key in the Authorization header.


Generate an API key in the dashboard. Use your API token in the Authorization header.

用語の選択を文書化してください。

概念	使う	使わない
認証情報	API key	API token、secret key、access key
設定ファイル	config file	settings file、preferences file
コマンドライン	CLI	terminal、command prompt、shell

書式を統一する

同じ種類のコンテンツには、同じ書式を使います。

• UI 要素：太字（Saveをクリック）
• コード／コマンド：バッククォート（npm install）
• ファイルパス：バッククォート（/etc/config.yaml）
• 初出の重要用語：太字または斜体
• プレースホルダー：SCREAMING_CASE または山括弧（YOUR_API_KEY または <api-key>）

LLM に適したパターン

前提条件を明確に示す

開始前に必要なものを列挙します。これにより、人間にも LLM にも文脈が伝わりやすくなります。

## Prerequisites

Before you begin, ensure you have:

- Node.js 18 or later installed
- An active account with admin permissions
- Your API key (find it in **Settings > API**)

略語は初出時に定義する

ページ内で略語が最初に登場したときは、正式名称を記載します。

The CLI (Command Line Interface) provides tools for managing your resources.
Subsequent uses can just say "CLI."


The CLI provides tools for managing your resources.

完全で実行可能なコード例を提示する

コピーして実行できるコード例にします。次の要素を含めます。

• 必要なすべてのインポート
• 現実的なプレースホルダー値
• 期待される出力（役立つ場合）

```python
import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.example.com/v1"

response = requests.get(
    f"{BASE_URL}/users",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

print(response.json())
# Output: {"users": [{"id": 1, "name": "Alice"}, ...]}

response = requests.get(url, headers=headers)

### Write Descriptive Titles and Meta Descriptions

Page titles and descriptions help with search and LLM understanding.

```markdown
---
title: "Authentication - API Reference"
description: "Learn how to authenticate API requests using API keys, OAuth 2.0, or service accounts."
---

避けるべき落とし穴

製品中心の表現を使わない

製品の機能ではなく、ユーザーの目標を軸にドキュメントを作成します。

# Send Emails

Send transactional emails to your users with delivery tracking.


# Email Service

Our powerful email service provides enterprise-grade delivery.

明白な手順は省く

説明がなくても分かる UI 操作はドキュメントに記載しません。

Enter your webhook URL. The URL must use HTTPS and be publicly accessible.


Click in the text field. Type your webhook URL. Click the Save button.

口語表現を避ける

口語表現は明瞭さとローカライズの妨げになります。

This approach significantly improves performance.


This approach is a game-changer for performance.
This will blow your mind.
Let's dive in!

品質の 2 つの側面

優れたドキュメントには 2 つの品質の層があり、2 つ目は 1 つ目を前提とします。

• 機能的品質 — 正確さ、完全性、一貫性、有用性、精密さなど、客観的で測定可能な品質です。これが前提となります。このガイドの原則と、種類ごとのスキルは、機能的品質を目標としています。
• 深い品質 — 主観的で人間中心の品質です。使い心地がよく、読者のニーズを先読みし、人々の実際の働き方に合っていることを指します。まず機能的品質を満たさなければ、この品質には到達できません。適切な種類（上記）を選び、明快に記述することで、そのための条件が整います。

品質モデルの全容と「改善による作業」のアプローチ（空のセクションの骨組みを作らず、実際のコンテンツを 1 つずつ改善すること）については、references/diataxis-compass.md を参照してください。

クイックリファレンスチェックリスト

ドキュメントを作成するときは、次の点を確認します。

• ドキュメントが明確な Diataxis の種類 1 つに該当し、複数の種類が混在していない（コンパスを参照）
• 「ユーザー」ではなく「あなた」を使用している
• 全体を通して能動態を使用している
• 不要な語句がない
• 見出しが内容を具体的に表している
• ページの内容だけで理解できる
• 見出しの階層が適切である
• 1 つの概念に対して用語が 1 つに統一されている
• 前提条件を記載している
• 略語を定義している
• コード例が完全である
• 製品中心の表現がない
• 口語表現がない

このスキルの適用

次の場合に、これらの原則を適用します。

1. 新しいドキュメントの作成：最初からすべての原則を適用します
2. ドキュメントのレビュー：クイックリファレンスチェックリストに照らして確認します
3. 既存ドキュメントの編集：まず文体とトーンを整え、次に構成、最後に一貫性を優先します
4. コード例の作成：完全で実行可能であることを確認します