howto-docs

ハウツードキュメントスキル

このスキルでは、効果的なハウツーガイドをドキュメントに記述するためのパターンを紹介します。ハウツーガイドは、具体的な目標を持つユーザー向けの、タスク指向のコンテンツです。

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

目的と対象読者

対象読者：

• 達成したい具体的な目標があるユーザー
• 製品にある程度精通していることを前提とします（まったくの初心者ではありません）
• 実用的で、すぐに実行できる手順を探しています
• 概念を学ぶのではなく、目的を達成したいと考えています

ハウツーガイドに含まれないもの：

• 探索しながら学ぶチュートリアル
• 理解を深める解説
• システムについて説明するリファレンスドキュメント

ハウツーガイドのテンプレート

すべてのハウツーガイドで、次の構成を使用してください。

---
title: "How to [achieve specific goal]"
description: "Learn how to [goal] using [product/feature]"
---

# How to [Goal]

Brief intro (1-2 sentences): what you'll accomplish and why it's useful.

## Prerequisites

- [What user needs before starting]
- [Required access, tools, or setup]
- [Any prior knowledge assumed]

## Steps

### 1. [Action verb] the [thing]

[Clear instruction with expected outcome]

<Note>
[Optional tip or important context]
</Note>

### 2. [Next action]

[Continue with clear, single-action steps]

```bash
# Example command or code if needed

3. [番号を続ける]

[各ステップは、1つの独立したアクションにします]

動作を確認する

[成功を確認する方法 — ユーザーには何が見えるか、どのような状態になるか]

トラブルシューティング

[Solution or workaround] [Solution or workaround]

次のステップ

• [関連するハウツーガイド 1]
• [関連するハウツーガイド 2]
• [より詳しいリファレンスドキュメント]

## Writing Principles

### Title Conventions

- **Always start with "How to"** - makes the goal immediately clear
- Use active verbs: "How to configure...", "How to deploy...", "How to migrate..."
- Be specific: "How to add SSO authentication" not "How to set up auth"

### Step Structure

1. **One action per step** - if you write "and", consider splitting
2. **Start with action verbs**: Click, Navigate, Enter, Select, Run, Create
3. **Show expected outcomes** after key steps:
   ```markdown
   ### 3. Save the configuration

   Click **Save**. You should see a success message: "Configuration updated."

文脈を最小限にする

• なぜ動作するのかは説明せず、やり方だけを示します
• さらに詳しく知りたいユーザー向けに、解説へのリンクを掲載します
• 各ステップは、直ちに実行するアクションに絞ります

条件付きの命令形を使い、現実の状況に対応する

単一の確実な進行経路を示すチュートリアルとは異なり、ハウツーでは、さまざまな状況が入り交じる現実の中でユーザーを支援します。Diataxisでは、ステップを条件付きの命令形で示します。「Xをしたい場合は、Yを実行します。」とすることで、読者がそれぞれの状況や目標を持っていることを尊重できます。

• 状況に応じて分岐させます。 適切なアクションがユーザーの状況によって異なる場合は、すべてに同じ手順が当てはまるかのように書くのではなく、「ステージングにデプロイする場合は ENV=staging を設定します。本番環境では…を使用します」のように説明します。
• 予期しない事態に備えます。 スキルのあるユーザーが実際に遭遇する失敗や回避策を記載します（これらは「トラブルシューティング」セクションで扱います）。
• 不要な内容は省きます。 ハウツーは、完全性ではなく、実用性を重視します。読者の目標達成につながらない内容は省き、網羅的な詳細についてはリファレンスにリンクします。

達成できることをガイドのタイトルにする

タイトルには、ユーザーの目標に基づいて、ガイドで達成できることを具体的に示します。「支払い」や「Stripeモジュール」ではなく、「Stripe決済を統合する方法」とします。具体的な成果をタイトルにできない場合は、執筆する範囲がまだ明確ではありません。

ユーザーの視点

製品ではなく、ユーザーの視点から書きます。

避ける表現（製品中心）	推奨する表現（ユーザー中心）
「APIは受け付けます…」	「リクエストを送信します…」
「システムは…します」	「…が表示されます」
「この機能を使うと…できます」	「これで…できます」

前提条件セクション

必要なものを明確に記載します。

## Prerequisites

- An active account with admin permissions
- API key generated from Settings > API
- Node.js v18 or later installed
- Completed the [initial setup guide](/getting-started)

ハウツーガイドの構成要素

Stepsコンポーネント

番号付きの手順には、Stepsコンポーネントを使用します。

<Steps>
  <Step title="Create a new project">
    Navigate to the dashboard and click **New Project**.
  </Step>
  <Step title="Configure settings">
    Enter your project name and select a region.
  </Step>
  <Step title="Deploy">
    Click **Deploy** to launch your project.
  </Step>
</Steps>

複数の選択肢を示すコードグループ

異なる方法を示す場合は、次のようにします。

<CodeGroup>
```bash npm
npm install @company/sdk

yarn add @company/sdk

pnpm add @company/sdk

```

Callouts for Important Information

<Warning>
This action cannot be undone. Make sure to backup your data first.
</Warning>

<Note>
This step may take 2-3 minutes to complete.
</Note>

<Tip>
You can also use keyboard shortcut Cmd+K for faster navigation.
</Tip>

展開可能なセクション

手順の流れを妨げないように、任意の詳細には次のような形式を使用します。

<Expandable title="Advanced options">
  If you need custom configuration, you can also set:
  - `timeout`: Request timeout in milliseconds
  - `retries`: Number of retry attempts
</Expandable>

ハウツーガイドの例

---
title: "How to set up webhook notifications"
description: "Learn how to configure webhooks to receive real-time event notifications"
---

# How to Set Up Webhook Notifications

Configure webhooks to receive instant notifications when events occur in your account. This enables real-time integrations with your existing tools.

## Prerequisites

- Admin access to your account
- A publicly accessible HTTPS endpoint to receive webhooks
- Completed the [authentication setup](/getting-started/auth)

## Steps

<Steps>
  <Step title="Navigate to webhook settings">
    Go to **Settings** > **Integrations** > **Webhooks**.
  </Step>

  <Step title="Add a new webhook endpoint">
    Click **Add Endpoint** and enter your webhook URL:

    ```
    https://your-domain.com/webhooks/receiver
    ```

    <Note>
    Your endpoint must use HTTPS and be publicly accessible.
    </Note>
  </Step>

  <Step title="Select events to subscribe">
    Choose which events should trigger notifications:

    - `user.created` - New user sign up
    - `payment.completed` - Successful payment
    - `subscription.cancelled` - Subscription ended

    Select at least one event to continue.
  </Step>

  <Step title="Save and get your signing secret">
    Click **Create Webhook**. Copy the signing secret shown - you'll need this to verify webhook authenticity.

    <Warning>
    Store the signing secret securely. It won't be shown again.
    </Warning>
  </Step>
</Steps>

## Verify it worked

Send a test event by clicking **Send Test** next to your webhook. You should receive a POST request at your endpoint with this structure:

```json
{
  "event": "test.webhook",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {}
}

エンドポイントのログを確認し、受信を確認します。

トラブルシューティング

- エンドポイントにパブリックアクセスできることを確認してください - SSL 証明書が有効であることを確認してください - サーバーが 30 秒以内に 2xx ステータスで応答することを確認してください - 正しい署名シークレットを使用していることを確認してください - 生のリクエストボディを読み取っていることを確認してください（解析済みの JSON ではありません） - [署名検証ガイド](/reference/webhook-signatures)を参照してください

次のステップ

• Webhook 署名の検証方法
• Webhook イベントリファレンス
• Webhook の再試行処理方法

## Hard gates (before publishing)

Complete in order. Do not treat the doc as ready until each gate passes.

1. **Goal lock** — Title starts with `How to` and names a specific outcome (verb + object). **Pass:** a reader can state what they will have done after following the guide, in one sentence, without reading the steps.

2. **Prerequisites closed** — Everything required before step 1 is listed (access, tools, versions, prior guides). **Pass:** you cannot name a blocker that belongs in Prerequisites but is missing from the list.

3. **Steps are atomic** — Each numbered step is one primary action; split if you would join with “and then” for unrelated actions. **Pass:** each step has a clear next action; risky steps (save, deploy, delete) state what the user should see after.

4. **Success is observable** — The “Verify it worked” section names concrete signals (UI text, exit code, HTTP status, file path, log line). **Pass:** the reader can confirm success without interpreting vague “it works.”

5. **Checklist complete** — Run the checklist below; every item is honestly yes or the guide is not ready to ship. **Pass:** all boxes checked.

## Checklist for How-To Guides

Before publishing, verify:

- [ ] Title starts with "How to" and describes a specific goal
- [ ] Prerequisites section lists all requirements
- [ ] Each step is a single, clear action
- [ ] Action verbs start each step (Click, Enter, Select, Run)
- [ ] Expected outcomes shown after key steps
- [ ] Verification section explains how to confirm success
- [ ] Troubleshooting covers common issues
- [ ] Next steps link to related content
- [ ] No unnecessary explanations - links to concepts instead
- [ ] Written from user perspective, not product perspective

## When to Use How-To vs Other Doc Types

| User's mindset | Doc type | Example |
|---------------|----------|---------|
| "I want to learn" | Tutorial | "Getting started with our API" |
| "I want to do X" | How-To | "How to configure SSO" |
| "I want to understand" | Explanation | "How our caching works" |
| "I need to look up Y" | Reference | "API endpoint reference" |

For the full compass procedure and the other type distinctions, see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

## Related Skills

- **[docs-style](../docs-style/SKILL.md)**: Core writing conventions and components
- **[Diataxis compass](../docs-style/references/diataxis-compass.md)**: Type selection, the 2×2 map, and the quality model
- **[tutorial-docs](../tutorial-docs/SKILL.md)**: Tutorial patterns for learning-oriented content
- **[reference-docs](../reference-docs/SKILL.md)**: Reference documentation patterns
- **[explanation-docs](../explanation-docs/SKILL.md)**: Conceptual documentation patterns