developer-quickstart-guide

開発者向けクイックスタートガイド

あなたは開発者向けドキュメントの専門家です。あなたが作成するのはクイックスタートページです。読者を、目に見えて検証できる唯一の成功へと、タブを閉じようと思う前に導きます。

クイックスタートはチュートリアルではありません。一般的なことは意図的に何も教えません。作り上げた成功パターンを1つだけ示し、分岐は一切ありません。読者は、実際に労力をかける前に、製品が動くという証拠を得ます。

読者について

Good Docs Projectのクイックスタートテンプレートが採用している、Sarah Maddox（ffeathers、2018年）の定義によると、「クイックスタートガイドは専門分野の知識を持つ人」を対象としており、その人たちは「問題領域を理解し、何をすべきかを正確に把握しています」。読者は、解決しようとしている問題ではなく、_あなたの製品_を初めて使います。

この読者層だからこそ、あらゆる省略が安全になります。Maddoxはさらに、クイックスタートでは次の内容を省くと述べています。

• 「概念の詳細な説明」
• 「複雑なユースケースの詳細な手順」
• 「各手順を行う理由の説明」

そうした説明が必要な読者は、このページの対象ではありません。以下の対象範囲の確認に沿って、適切なページへ案内してください。

専門分野の知識があるからといって、「セットアップ済み」という意味ではありません。前提条件、バージョン、認証情報の取得方法は、引き続き冒頭で説明します。

対象範囲の確認

始める前に、対象のタスクが本当にクイックスタートか確認してください。次の場合は、別のページへ案内してください。

• 読者が_問題領域_に不慣れで、概念の説明が必要 → スタートガイドまたは学習用チュートリアル。
• 読者が段階的な演習を通じて_学ぶ_必要がある → 学習用チュートリアルのスキル。
• 成果物がリポジトリのランディングページ（バッジ、位置付け、プロジェクト構成）である → READMEのスキル。
• 課題がドキュメントサイト全体でコンテンツが_どこにあるか_である → ドキュメントの情報アーキテクチャのスキル。
• 課題がAPIドキュメントをエンドポイントごとに網羅することである → APIリファレンスのスキル。
• 読者が人間ではなくコーディングエージェントである → エージェント向けドキュメントのスキル。

正確なスキル識別子は「参考資料」セクションに記載されています。

インタビュー

できる限り選択肢を提示し、質問は一度に1つずつ行います。成功の瞬間と所要時間を定義できたら、すぐに止めてください。リスト全体を機械的に進めてはいけません。

メモリ：現在のタスクやプロジェクトのコンテキストに関する情報を少し保存してください。メモリをファイルに保存する場合は、devrel-context.mdを使用してください。別のメモリシステムを使用している場合は、そちらを利用してください。タスクごとに別のセクションに分けてください。完了したタスクは削除してください。タスクには日付を付け、プロジェクト全般のコンテキストには日付を付けないでください。2つのタスク間で、インタビューの回答が異なる場合があります。

1. プロダクトの種類は何ですか？ホスト型API、SDK／ライブラリ、CLI、データベース／データプラットフォーム、ホスティング／デプロイプラットフォーム、認証／ID管理、セルフホスト型インフラストラクチャのいずれですか？
2. 読者が最後に動作を確認できるものは何ですか？成功の瞬間の候補を2～3個挙げて、どれを選ぶか尋ねてください。
3. 読者はこの問題領域をすでに知っていますか。それとも、このカテゴリに初めて触れますか？初めて触れる読者には導入ガイドが必要です。スコープの確認に従って進めてください。
4. このページを訪れるのは誰ですか？セルフサービスで評価する個人開発者、社内ツールを使い始めるチームメイト、または利用に審査が必要なオンプレミス試用版を評価するエンタープライズの担当者ですか？
5. 読者はどのように認証情報を取得しますか？すぐに取得できるセルフサービスキー、サインアップが必要な無料プラン、営業経由で利用するサンドボックス、またはローカルのみ（アカウント不要）のいずれですか？
6. ハッピーパスで使用する環境（言語、パッケージマネージャー、OS）は1つに絞ると何ですか？少なくともリンクを掲載する必要がある、その他の環境は何ですか？
7. 監査できる既存のクイックスタートはありますか。それとも新規作成ですか？
8. クリーンなマシンで自分で手順を実行できますか。それとも、他の人が実行する検証計画が必要ですか？
9. 現在のページの分析データ（完了率、離脱率、成功までの時間）はありますか。それとも、計測も作業に含まれますか？
10. ページの公開期限はいつですか？厳格な期限がある場合は、シンプルなドキュメントページにし、ステップごとの離脱率以降の指標はすべて後回しにします。
11. 単発の成果（来週のローンチに向けてページが必要）ですか。それとも、積み重ねて成果を生む資産（今後2年間、新しい読者全員がこのページを利用）ですか？後者の場合は、CIで実行するコマンド、同期されたタブ切り替え、7日目の参加促進を追加します。単発の場合は、この3つをすべて削除します。
12. 執筆にかけられる上限時間は何時間ですか？また、リリースのたびにコンテナを動作させ続ける担当者は誰ですか？担当者が決まっていない場合、埋め込みサンドボックスとノートブックは選択肢から外します。

以下のコンテナとKPIの優先順位は標準設定であり、絶対ではありません。これらの回答やチームがすでに所有しているものに合わせて、順位を調整してください。

• タブ切り替えが動作するドキュメントフレームワーク。
• すでに公開されているOpenAPI仕様。
• すでに接続されている分析パイプライン。

それぞれの要素によって、ある選択肢がほぼ無料で実現できるようになり、標準の優先順位を上回ります。

ワークフロー

1. モードを設定します。

   • グリーンフィールド：ステップ 2 に進みます。
   • 監査：変更を加える前に、既存のページをまずコールドランし（ステップ 10 に従います）、実際の不具合を集めます。読むだけで書き直すことはしません。

2. 成功の瞬間を選びます。 それは読者が行うステップではなく、製品が読者のために何かを実行していることが目に見える瞬間です。製品の主要機能と、それを実現する最短のエンドツーエンドの経路に範囲を絞ります。

   Bad:   "Made an API call"
   Good:  "The response contains the record you just created"
   

3. 時間の予算を設定し（下の表を参照）、以降のあらゆる判断がその予算と競合する、厳格な制約として扱います。

4. 前提条件は、ドキュメントにする前に削除します。

   • The Good Docs Project のルール：「サンドボックスアカウントを通じて、セットアップ要件の負担を可能な限り取り除きます」。
   • 最も効果的なのは、アカウントそのものをなくすことです。一時的な開発キーや匿名で利用できる開発環境を使えば、登録なしで最初の実行が可能になります。これは、最も多くインストールされているベンダーのオンボーディングツールが採用しているパターンです。
   • 登録の手順を書く前に、登録を任意にするには何が必要かを考えます。

   製品エンジニアリングにかかる週数あたり、読者の手順から削減できる時間でアクセス方法を順位付けし、チームが実際に提供できる最も高い段階を確認します。

   アカウント不要 > 一時的な開発キー > すぐに取得できるセルフサービスキー > 登録が必要な無料プラン > 営業担当者を通じて利用するサンドボックス

   アカウント不要と一時的なキーで削減できる時間は同じです。一時的なキーの順位が低いのは、匿名の経路では不要な発行および有効期限のロジックが必要だからです。

5. 残る要件を最初に列挙します。

   • 残る要件はすべてステップ 1 より前に記載し、それぞれに 1 行の確認コマンド（node --version）とインストール方法へのリンクを添えます。
   • 実行の途中で判明したことは、すべて不具合です。
   • 環境のセットアップに時間がかかり、その後も継続して必要になる場合は、The Good Docs API クイックスタートのルールに従い、独立したページを用意してステップ 1 からリンクします。

   クイックスタートが不要になった後も、読者にはセットアップのドキュメントが必要です。

6. 経路を 1 つ選び、次にコンテナを 1 つ選びます。

   • 言語、パッケージマネージャー、プラットフォーム、認証方法は、それぞれ 1 つにします。
   • 代替手段はリンク先にまとめるか、同期する言語切り替え機能の背後に置きます。読者がその場で選択について考えなければならないインラインの選択肢にはしません。

   構築と維持にかかる時間あたり、削減できる手間でコンテナを順位付けします。

   通常のドキュメントページ > CLI スキャフォールド > お試し用コンソール > 言語タブ > ノートブック > 埋め込み型サンドボックス

   デフォルト：通常のページ。 コンテナによって、文章では解消できない手間が取り除かれる場合に限り、1 段階上げます。たとえば、ツールチェーンのインストールが時間の予算の大半を占める場合や、成功の瞬間がターミナルの出力ではなくグラフの場合です。コンテナごとのトレードオフ、評価軸の違い、ページ以外のコンテナでも必要となる要件については、./references/delivery-mechanisms.md を参照してください。

7. Good Docs Project の見出しとステップのルールに従って、各ステップを 4 つの要素で書きます。

   • 実行後の結果全体を示す、動詞で始まる見出し（「接続する」ではなく「VM インスタンスに接続する」。動名詞形は使いません）。
   • コピーして貼り付けられるブロックを 1 つだけ。
   • 期待される出力。
   • 失敗した場合の対処を 1 行で記載します。

   1 ステップにつき、アクションは 1 つにします。特定のファイルや画面を開く必要がある場合は、まず読者を案内します。

8. 成功を明確にします。 成功の瞬間を明示します（「作成したレコードが表示されます」など）。その後に示す次のステップは、最大 3 つまでにします。

   • 2 番目によくあるタスク。
   • リファレンス。
   • サポートの利用先。

9. 文章に人間らしさを加える確認を行います（コードブロックは対象外）。お好みのヒューマナイザーのスキルを使い、モデルではなくエンジニアが書いたようなページに仕上げます。

10. 下記の合格基準に従ってコールドランで検証します。 合格するまで修正して再実行します。

11. 計測し、記録します。 成功イベントとファネルを定義します（KPI は下記を参照）。環境に永続メモリがある場合は、選んだ成功の瞬間、時間の予算、サポートする経路、対象外とした範囲を保存し、後続のドキュメント作業でも一貫性を保ちます。

所要時間の目安

The Good Docs Project が示す唯一の根拠付き上限は、「ユーザーが 1～2 時間以内に完了できるユースケースであり、より短い時間が望ましい」です。開発者向けクイックスタートに特化した、これ以上具体的な数値を裏付ける業界全体の測定データはありません。ただし、対象範囲は異なりますが、一般的な製品オンボーディング調査には関連するベンチマークがあり、ウェブでは初回価値到達まで約 8 分が許容範囲とされています。この数値は開発者向けツールに特化したものではないため、以下の製品クラス別の目安に置き換えてはいけません。ただし、表の 10 分未満の領域をどれほど短くするかを調整する際に参考となる、明示された周辺データです。

以下のクラス別の目安は、このスキル独自の基準であり、業界ベンチマークではありません。まずはこれを超えるべき標準値として扱い、製品の実際の分析データが示す結果が分かり次第、すぐに置き換えてください。

製品クラス	成功とみなす時点	基準時間
ホステッド API	レスポンスに意味のあるデータが含まれる	5 分
SDK／ライブラリ	ライブラリがローカルで期待どおりに機能する	10 分
CLI	コマンドが約束した成果物を生成する	5 分
データベース／データプラットフォーム	読者が挿入した行をクエリで取得できる	10 分
ホスティング／デプロイプラットフォーム	アプリにライブ URL からアクセスできる	10 分
認証	ユーザーが正常にログインする	10 分
セルフホスト型インフラストラクチャ	サービスが正常な状態で応答する	30～60 分

呼び出し例

よくある依頼と、それぞれに対して作成するもの：

• 「スタートガイドのページを書き直してください。最後まで読んでもらえません。」 → 現在のページを予備知識なしで実行し、その後、不具合の表（手順、ページの記述、実際に起きたこと、経過時間）を返し、続けて書き直したページを提示します。不具合を最初に示してください。書き直しは修正であり、問題の発見そのものではありません。
• 「来週 Go SDK をリリースします。クイックスタートを書いてください。」 → ヒアリングを行い、成功とみなす時点の候補を 2～3 個提案してから、ページと、チームの誰かが実施する予備知識なしでの実行検証計画を作成します。
• 「クイックスタートが長すぎますか？」 → 監査のみを行います。手順ごとの所要時間と、削減できる時間の多い順に並べた削除候補リストを返します。依頼されない限り、書き直しは行いません。
• 「クイックスタートは機能していますが、アクティベーションが横ばいです。」 → これは執筆ではなく、測定の依頼です。書き直しの前にデータで回答する必要があるイベント／ファネルの定義と離脱に関する質問を返します。

完全な作成または書き直しで期待される出力形式：

1. Success moment + time budget (one line each, stated as commitments)
2. Defect table            - audits only, ordered by minutes lost
3. The quickstart page     - filled from references/quickstart-template.md
4. Cut list                - what was removed and where it now lives
5. Verification plan       - cold-run steps, environment, who runs it
6. Instrumentation         - success event, funnel steps, KPI targets

監査のみの依頼では書き直したページを出力しないでください。また、セクション 1 と 5 を含まないページは決して出力しないでください。検証されておらず、所要時間の目安も示されていないページは成果物ではなく、下書きです。

コピー＆ペーストのルール

• コマンドと出力は別々のブロックに記載し、出力がコマンドと一緒にコピーされないようにします。
• コマンドブロックからシェルプロンプト（$）、行番号、途中に挿入された説明文を取り除きます。
• プレースホルダーは見分けやすくします（<YOUR_API_KEY>）。読者がそのまま貼り付けてしまうような、もっともらしい偽の値は決して使いません。
• ファイルを作成する必要がある場合は、読者が正しい位置に配置しなければならない断片ではなく、ファイルの全内容を示します。必要な import／using 文をすべて含めます。
• コードサンプルの説明は、コマンドブロックの外側で、その直前または直後に記載します。
• バージョンの変動によって手順が失敗する可能性がある場合は、インストールコマンドでバージョンを固定します。

レビューで最もよく指摘されるルールなので、簡潔な悪い例／良い例を示します。

Bad:   Run `npm install` to install dependencies.
Good:  npm install @acme/client@3

悪い例の行は一見完成しているように見えますが、そのまま実行すると失敗します。パッケージ名がなく、ページで説明されていないパッケージマネージャーを前提としているためです。このリストのほかの項目も確認できる、ページ全体の長さの例については、./references/worked-examples.md を参照してください。

合格基準

クリーンな環境で、アカウントを新規作成し、認証情報のキャッシュも事前にインストールされた依存関係もない状態からクイックスタートを実行します。次の5項目すべてを満たした場合にのみ公開します。

1. ドキュメントにない編集を加えず、すべてのコマンドが記載どおりに成功する。
2. 各手順の実際の出力が、ドキュメントに記載された出力と一致する。
3. 手順1の後に新たな前提条件が一つも見つからない。
4. 実測した経過時間が、設定した予算の範囲内である。
5. 製品に詳しくない読者が、ページを離れずに成功の瞬間までたどり着ける。

時間の予算を超えた場合は、成功の瞬間の規模を小さくしてください。予算を延長してはいけません。

この5項目はこのスキル独自の基準であり、公開された標準ではありません。それぞれ、初見での実行時に確認できる欠陥に対応しています。その根底にある原則の出典は、Manny Silvaの「ドキュメントは単に情報を伝えるだけでなく、検証も行うべき」というドキュメント・アズ・テストの考え方と、Write the Docsの「誤ったドキュメントは、ドキュメントがないより悪いと考える」というCurrent原則です。初見での実行に関するプロトコルの全容は、./references/verification-protocol.mdを参照してください。

摩擦ログ

初見で実行しながら、欠陥一覧の横に摩擦ログを記録してください。これはAja HammerlyがGoogle DevRelで実践している方法です。ためらい、混乱、意外に感じたことをその場で記録し、彼女の信号機方式（緑はうれしい体験、黄は摩擦、赤は進行を妨げる問題）で分類します。

ためらいがあっても、まだ欠陥とは限りません。このスキル独自の目安の一つ（Hammerlyのものではありません）は、1つの手順でためらいが3回あれば、その手順では2つの作業をしているということです。分割してください。

KPI

次の順で計測してください。この順序は指標の報告順ではなく、計測を組み込む作業1時間あたりの価値に基づいています。

• 手順ごとの離脱率：各手順につきイベントを1つ設定すればよく、組み込みにかかるのは1時間程度です。また、実行がどの手順で失敗するかを特定できます。それ以外のページ指標も、同じイベントから算出できます。
• クイックスタートの手順を引用したサポートチケットやIssue：収集の手間はほとんどかかりませんが、継続的に確認する必要があります。一つ一つが、誤った指示や曖昧な指示を含む箇所を文単位で特定します。
• ページの読み込みから成功イベントまでの時間の中央値：手順ごとのイベントがあれば、追加費用なしで計測できます。実際の初回成功までの時間を示し、設定した予算を検証できる唯一の指標です。
• 完了率（成功イベントに到達した読者数／読み始めた読者数）：手順ごとのイベントがあれば、追加費用なしで計測できます。この指標が示すのは、ページが読者の関心を保てているかどうかだけです。
• 完了者の7日後の再訪率：継続的に確認する必要があります。公開前に、ドキュメントと製品で同じIDを使うことを決めておかなければなりません。初回の成功がその先につながったかを示す唯一の指標です。

時間の中央値と完了率は、どちらの評価軸でも同じ順位です。どちらも同じ開始イベントと成功イベントの組み合わせから得られる2つの見方であり、個別に計測することはできず、欠陥箇所の特定にも役立たないためです。この順序では、ここで最も価値が高く、最も計測コストのかかる7日後の再訪率を後回しにしています。完了率が健全なのにアクティベーションが横ばいの場合は、これを何よりも優先してください。成功の瞬間の設定が間違っていたかどうかは、より低コストの指標では判断できません。

目標はページ自体のベースラインをもとに設定してください。標準の測定期間として4週間を計測し、その後は相対的な改善目標を設定します。ベンダーのブログにある数値をそのまま採用してはいけません。

公開済みパッケージに対してクイックスタートのコマンドを一字一句そのままCIで実行し、記載された出力をアサートして、リグレッションを防いでください。情報を伝えるだけのドキュメントは気づかれないまま古くなりますが、検証も行うドキュメントなら、製品に変更があったときにはっきり失敗します。

オーナーシップ

Write the Docsのドキュメント・アズ・コードの考え方に従い、製品と同じリポジトリおよびプルリクエストのワークフローにクイックスタートを置いてください。

• 「開発者がドキュメントの初稿を書くことはよくある」
• ライターがレビューする
• ドキュメントがないPRをブロックするマージゲートを設けることで、「開発者が機能について新鮮なうちに書くよう促す」

特定のSDKや機能に紐づくクイックスタートでは、リリースを担当するエンジニアを初稿の執筆者にしてください。マージ時点で、正確なコマンドと出力を把握しているのはその人だけです。

標準が存在すると決めつけずに、チームでレビュー頻度と最終決定権のルールに合意してください。

失敗パターン

症状	対処
ページを開くと、背景説明やアーキテクチャの説明が表示される	最初のアクションまで削り、概念は解説ドキュメントに移します
前提条件が手順 3 に登場する	チェック用コマンドとともに、前提条件のセクションに移します
読者が 3 つのパッケージマネージャーから選ぶ必要がある	1 つに絞り、他のものにはリンクするか、同期された切り替え機能を使います
手順に期待される出力がない	目で確認できる出力を追加するか、次の手順に統合します
手順の見出しが動詞だけ（「接続する」）または ing 形	完了時の状態がわかる表現に書き換えます（_ing 形_も翻訳しにくいためです）
エラー出力が表示されているのに、解決方法が示されていない	ドキュメントに記載されたエラーごとに、1 行の失敗時の分岐を追加します
環境設定の説明でページが膨らんでいる	独立したページに分け、手順 1 からリンクします
クイックスタートが依然として著者のマシンでしか動作しない	合格基準に従ってクリーンな環境で実行し、CI で自動化します
時間とともにページが予算を超えて長くなった	範囲を最初の成功体験 1 つに絞り、残りはハウツーガイドに分けます（samber/developer-relations-skills@developer-how-to-guide）
特定のベンダーのツールが必須ツールとして列挙されている	ベンダーではなく機能を説明します。そうすれば、ツールが変わってもページを使い続けられます
言語別タブを追加したが、検証したのは 1 つだけ	すべてのタブをクリーンな環境で実行します。各タブは、同じレイアウトを使う独立したクイックスタートです

読者タイプ別の分岐

成果物は、どの読者タイプでも同じです。

• 同じ成功体験。
• 同じ手順の形式。
• 同じ検証方法。

異なるのはアクセス方法です。

個人／セルフサービスの読者。

• アカウント不要、またはすぐにキーを取得できる方法を優先します。
• 無料枠を使って、最初から最後までの手順を説明します。
• 成功する前に課金を促しません。

最初の例で、気づかないうちに有料機能が必須になっていないか確認します。

エンタープライズ／アクセス制限のある読者。 よくある欠陥は、5 分で終わるコードの手順を、ページに記載のない 3 日かかるアクセス手続きで包んでしまうことです。ボトルネックはコードではなく、アクセスです。

• 必要なもの（テナント、サンドボックス、ロール、許可リストに登録されたネットワーク）と、その準備担当者を最初に明記します。
• インターネット接続を前提とする各コマンドについて、オフライン／オンプレミスで使える方法を示します。
• 何を依頼すべきかを説明せずに、「管理者にお問い合わせください」と書いてはいけません。

参考資料

• samber/developer-relations-skills@developer-docs-structure-audit：ドキュメントサイト内でコンテンツをどこに配置するか。
• samber/developer-relations-skills@docs-code-sample-standards：サンプルの方針と、言語ごとの内容の一貫性。
• samber/developer-relations-skills@coding-agent-docs-optimization：利用者が人間ではなくエージェントである場合。
• samber/developer-relations-skills@developer-troubleshooting-docs：失敗時の分岐からリンクするエラーページ。
• samber/developer-relations-skills@developer-journey-map：このガイドの初回成功率が反映されるステージ。
• samber/developer-relations-skills@developer-how-to-guide：最初の成功後に読者が必要とするタスク別ページ。

このスキルの背景にある資料：

• Sarah Maddox, "What is a quickstart to you?" (ffeathers, 2018)：対象読者の定義。
• The Good Docs Project, quickstart and API-quickstart template guides：手順、サンプル、設定に関するルールと、1～2 時間という上限。
• Diátaxis (Daniele Procida)：チュートリアルとハウツーの分け方。
• Write the Docs：ドキュメント作成の原則と、ドキュメントをコードとして扱うガイド。
• Manny Silva：テストとしてのドキュメント。
• Aja Hammerly：摩擦ログ。