help-docs-writer

ヘルプドキュメントライター

製品機能に関する顧客向けヘルプ記事を作成します。技術的な実装と、ユーザーにわかりやすいドキュメントをつなぎます。

入力

AskUserQuestion を使用して、次の情報を収集します。

入力	必須	説明
機能名	はい	ドキュメントを作成する機能
対象読者	はい	技術的な知識レベル（初級／中級／上級）
出力形式	いいえ	markdown（デフォルト）または html
ヘルプセンタープラットフォーム	いいえ	Zendesk、Intercom、Notion、GitBook、カスタム

プロセス

1. 機能の調査

コードベースで機能の実装を検索します。

# Find feature files
rg -l "feature_name" --type-add 'code:*.{rb,js,ts,py,jsx,tsx}'

# Find UI components
rg -l "FeatureName" src/ app/

# Find routes/endpoints
rg "feature" config/routes.rb app/controllers/

以下を抽出します。

• 機能の内容（主な機能）
• ユーザーが利用できる入口（ボタン、メニュー、URL）
• 設定オプション
• エラー状態と例外ケース

2. 記事の構成

ヘルプ記事の標準的な構成：

1. Title (action-oriented)
2. Overview (what + why, 2-3 sentences)
3. Prerequisites (if any)
4. Step-by-step instructions
5. Tips/best practices (optional)
6. Troubleshooting (common issues)
7. Related articles (links)

3. 顧客向けの文章を作成

• 読者に語りかける（「あなた」）、現在形、能動態を使い、専門用語を避けます
• 番号付きの手順：各手順は1つの操作にし、動詞で始め、操作ごとに期待される結果を記載します

記事テンプレート

機能の手順ガイド

# How to [Action] with [Feature]

[One sentence: what this helps you do]

## Before you start

- [Prerequisite 1]
- [Prerequisite 2]

## Steps

1. **[Action verb] [object]**

   [Where to find it / what to click]

   ![Screenshot placeholder: description]

2. **[Next action]**

   [Details]

3. **[Final action]**

   You'll see [confirmation message/result].

## Tips

- [Tip 1]
- [Tip 2]

## Troubleshooting

### [Problem statement as question]

[Solution in 1-2 sentences]

### [Another common issue]

[Solution]

## Related articles

- [Link to related feature]
- [Link to related feature]

クイックリファレンス

シンプルな機能の場合：

# [Feature Name]

[What it does in one sentence]

**To use [feature]:**

1. Go to **[Location]**
2. Click **[Button/Link]**
3. [Complete the action]

**Note:** [Important caveat if any]

設定ガイド

# [Feature] settings

Customize how [feature] works for your account.

## Available settings

| Setting | Description | Default |
|---------|-------------|---------|
| [Name] | [What it controls] | [Value] |
| [Name] | [What it controls] | [Value] |

## How to change settings

1. Go to **Settings > [Section]**
2. Find **[Setting name]**
3. [Instructions to modify]
4. Click **Save**

Changes take effect [immediately/after X].

執筆ガイドライン

手順の説明

すること	しないこと
Save をクリックします	Save ボタンをクリックします
タイムゾーンを選択します	希望するタイムゾーンを選びます
メールアドレスを入力します	メールアドレスを打ち込みます

UI 要素の書式

• クリックできる要素（ボタン、リンク、メニュー項目）は 太字 にします
• ユーザー入力、URL、技術的な値は コード にします
• 強調には 斜体 を使います（控えめに）
• ユーザーに表示される正確な文言は「引用符」で囲みます

スクリーンショットのプレースホルダー

視覚的な説明のため、プレースホルダーを含めます。

![Screenshot: Settings page with Save button highlighted]

形式：![Screenshot: [description of what to capture and highlight]]

コールアウト

重要な情報に使用します。

> **Note:** [Important information]

> **Warning:** [Potential issue or destructive action]

> **Tip:** [Helpful suggestion]

出力形式

Markdown（デフォルト）

以下を含む標準的な Markdown：

• ATX 見出し（#、##、###）
• フェンス付きコードブロック
• テーブル
• コールアウト用の引用ブロック

HTML

以下を含むセマンティック HTML：

• <article> ラッパー
• <h1> から <h3> までの見出し
• 番号付き手順用の <ol>
• データ用の <table>
• class="note|warning|tip" を指定したコールアウト用の <aside>
• インラインスタイルを削除（CSS クラスのみ）

HTML テンプレート：

<article class="help-article">
  <h1>[Title]</h1>

  <p class="intro">[Overview]</p>

  <section class="prerequisites">
    <h2>Before you start</h2>
    <ul>
      <li>[Prerequisite]</li>
    </ul>
  </section>

  <section class="steps">
    <h2>Steps</h2>
    <ol>
      <li>
        <strong>[Action]</strong>
        <p>[Details]</p>
      </li>
    </ol>
  </section>

  <section class="troubleshooting">
    <h2>Troubleshooting</h2>
    <details>
      <summary>[Problem as question]</summary>
      <p>[Solution]</p>
    </details>
  </section>

  <aside class="note">
    <p>[Important note]</p>
  </aside>
</article>

品質チェックリスト

提出前に、以下を確認します。

• タイトルが動詞または「方法」で始まっている
• 概要で内容と利点の両方を説明している
• 前提条件があれば記載されている
• 各手順が1つの操作になっている
• 手順が動詞で始まっている
• UI 要素が 太字 になっている
• 専門用語や定義されていない略語がない
• トラブルシューティングでよくある問題を扱っている
• スクリーンショットのプレースホルダーが含まれている
• 関連記事へのリンクがある

プラットフォーム固有の注意事項

Zendesk

• 再利用可能なコンテンツには {{snippet}} を使用します
• メタデータに記事ラベルを追加します
• 検索キーワードを含めます

Intercom

• 記事を1000語未満にします
• 専用のコールアウト構文を使用します：> 📌 Note:
• 最後にリアクションを促す文言を追加します

Notion

• トラブルシューティングにはトグルブロックを使用します
• 目次を追加します
• アイコン付きのコールアウトブロックを使用します

GitBook

• ヒント構文を使用します：{% hint style="info" %}
• ページの説明を追加します
• 複数プラットフォーム向けの手順にはタブを使用します

このスキルで対応しないこと

• スクリーンショットの生成（プレースホルダーのみ提供します）
• 他言語への翻訳
• 動画チュートリアルの作成
• API ドキュメントの作成（技術ドキュメントには docs-architect を使用してください）