get-up-to-speed

短時間で使いこなす

独立したクイックスタートワークスペースで、実行可能なサンプルを添えたクイックスタートガイドを1つ作成します。調査を行い、有用な進め方を選び、それを詳しく説明することで、すぐに始められるようにします。対象の中核となる機能とその関係を取り上げ、代表的なシナリオで掘り下げ、必要に応じて短い補足例を示します。

合意した範囲を1回の提供で完了します。ドキュメントの各セクションは読み進めやすくするための構成であり、続行の許可を待つ独立した学習セッションではありません。以降の会話では、ガイドの内容を明確化したり拡張したりします。学習者向けの演習、評価、学習記録は、このワークフローの対象外です。

英語での出力

英語の文章を書く、または改訂する前に、インストール済みのsimple-english スキルを使用してください。名前で読み込むか、そのSKILL.mdと該当する参照資料を読んでください。 このコンテキストですでに読み込まれた指示は再利用してください。 この規約を読んだ後、英語の進捗報告、草案、最終回答を送信する前に、依存関係を読み込んでください。

スタイル上のルールと矛盾する場合も、意味、不確実性、要件の強さ、専門用語、タスクで指定された形式を維持してください。要求された言語を使用してください。 コード、識別子、コマンド、原文の引用、歴史的な証拠を保持してください。

必要な指示を利用できない場合は、その不足を一度だけ報告し、独立して進められる作業を続けてください。依存関係が利用可能になるか、ユーザーが明示的に例外を許可するまでは、影響を受ける英語の出力を草案のままにしてください。依存関係を自動的にインストールしたり、未確認の草案がこの要件を満たすと主張したりしないでください。

1. 学習の背景を把握する

学習者がすでに身につけている言語の基礎を踏まえてください。プログラミング言語をゼロから教えること、体系的な基礎コース、長期的な学習計画は、ライブラリのクイックスタートの対象外です。そのような不一致がある場合は、教材の準備やワークスペースの作成に取りかかる前に説明し、別の方向性を選ぶか、依頼の範囲を絞るよう学習者に促してください。

依頼と利用可能なコンテキストから、対象、既存の経験、利用目的を把握してください。スイートの場合は、公式の概要を参照し、利用可能な進め方を確認してください。ガイドの内容に大きく影響する不足情報についてのみ質問してください。貢献の目的が示されている場合は、それだけで貢献準備の必要性が明らかになっています。

指導言語を定めてください。このクイックスタートで明示的に選択されている言語があればそれに従い、そうでなければ学習者に選択を求めてください。コードの識別子、コマンド、API名は一般的な表記のままにして、ガイドと会話でこの言語を使用してください。会話で使われている言語だけでは、選択したことになりません。

このガイドによって読者ができるようになることと、対象外とする高度な進め方や別の進め方を明確にしてください。語数、レッスン数、プロジェクト全体のカリキュラムを一律に課すのではなく、この到達目標をもとに詳細度を決めてください。

完了条件： 対象、目指す成果、関連する予備知識、範囲、指導言語が明確になり、代表的なシナリオを選べる状態になっていること。

2. 調査し、手順を実演する

公式の概要、スタートガイド、想定する用途に関するガイドを読みます。依頼で指定されたバージョン、または関連するインストール手順で示されたバージョンを選びます。新規セットアップでは、コントリビューションの対象が特定のソースリビジョンを指定していない限り、現行のドキュメントに記載されたリリースを使用します。実演するインストール、ドキュメント、ソースの対応関係を記録します。

対象の特徴的な判断や動作が明らかになるシナリオを選びます。そのシナリオに沿って、ほかの主要な機能とその関係を説明します。シナリオだけでは必要な概念を説明できない場合は、補足します。合意した範囲全体を準備してから引き渡します。

ドキュメントで十分に見える場合も、ソースの準備を行います。対応するソースを見つけ、関連するパッケージと公開エントリーポイントの構成を把握し、主要な動作、デフォルト、優先順位、制限を説明するために必要な実装とテストをたどります。ガイドの説明を裏付けられた時点で調査を終えます。公開契約と、調査したリビジョンにおける動作を区別し、読んだテストと実行したテストも区別します。

通常の導入では、ツールを使い、さまざまなケースに応じて判断できる深さで、主要な仕組みを説明に含めます。コントリビューションが目的の場合は、観測できる動作から関連する実装、最小限の変更、回帰テストまでをつなぐ一連の手順も準備します。

• エントリーポイントの見つけ方、重要な呼び出しやデータ変換のたどり方、動作を担う分岐の特定方法を説明します。
• 既存の適切な問題、過去の修正、または明示的にラベル付けした教材用の変更を使います。関連するテストのセットアップ、トリガー、アサーションと、その場所に変更を加える理由を説明します。また、変更前後のテスト結果から何が分かるかも説明します。教材用の変更は、上流のバグが存在する証拠ではありません。
• 教材用ワークスペース内の独立したチェックアウトで、関連するコントリビューションの準備、変更、対象を絞ったテストをリハーサルします。ベースリビジョン、再現可能なパッチまたは変更済みソース、再実行に必要なコマンドを保持します。コントリビューションの例を、ガイドの主要なシナリオに関連付けます。

指定された保存先、または現在のワークスペース内に新しく作成した get-up-to-speed-<target> ディレクトリにワークスペースを作成します。既存の内容は保持します。完全なガイドには README.md を使用し、コードとフィクスチャには examples/ を使用します。マニフェストと設定ファイルは、ツールが想定する場所に配置します。必要に応じて、補足するソースのチェックアウトや証拠も保持し、その説明をガイドに記載します。運用上の作業はこのワークスペース内で行います。既存プロジェクトの変更、サービスのプロビジョニング、コントリビューションの公開には、それぞれ別途承認が必要です。

例は自分で実行します。UI の例では実際に表示される画面を確認し、プログラムによる例ではコマンド出力または生成された成果物を確認します。例によって状態が変わる場合は、実行可能な変更前後の状態を保持します。通常のマニフェストとロックファイルで依存関係を記録し、インストールされたバージョンが準備内容と一致することを確認します。観測された動作と予定していた説明に食い違いがある場合は、該当する説明を記述する前に解決します。

対応するソースまたは実行環境を利用できない場合は、具体的な制約を示し、ドキュメントで裏付けられる主張、ソースから導いた説明、観測した結果、予想される結果を区別します。実行していない手順の説明で作成できるのは限定的なガイドであり、検証済みのコントリビューション手順の根拠にはなりません。証拠の不足によって目標を達成できない場合は、その阻害要因を説明し、裏付け可能な範囲を狭めるか、作業を延期するかを学習者に選んでもらいます。不完全なガイドに黙って置き換えてはいけません。

完了条件： 合意した範囲のすべての項目に、裏付けのある説明と再現可能な例があり、実行結果、または合意した成果をなお裏付けられる明示的な制約が示されていること。

3. 完全なガイドを作成する

元となる会話を読んでいない読者を対象にします。冒頭では、対象の目的、読者が達成すること、想定する背景知識、主要な概念と機能の簡潔な概要を示します。それらの関係と、代表的なシナリオがどこに当てはまるかを説明します。バージョン情報とセットアップ手順は見つけやすくしつつ、実行履歴が導入を占めすぎないようにします。

本文は、シナリオでの判断と動作を中心に構成します。重要な概念や手順ごとに、次の内容を含めます。

• それが必要となる問題を示し、読者がすでに知っていることと結びつけます。
• 関連するコードを本文に掲載し、実行可能なファイルへのリンクを示します。重要なコマンド、設定の選択肢、入力が結果に変わる仕組みを説明します。
• なぜその結果になるのかを説明します。条件を変えることで重要な違いが明らかになる場合は、小さな変更例を示し、その影響と限界を説明します。

コントリビューションの準備については、手順 2 で準備したソースの流れ、最小限の変更、回帰テストにも、同じ説明方法を適用します。流れを追うために必要なコード抜粋と理由を本文に含めます。ソースへのリンクは根拠と追加の読み物として示し、説明の代わりにしないでください。

この対象に合ったセクションや図を選び、決まったレッスンのテンプレートを繰り返す必要はありません。教えるために必要な内容はすべて主文書に含めます。最後に、実行可能な手順、必要に応じて簡潔なコマンドまたは API のリファレンス、対象範囲の境界、次に読むべき関連資料を示します。扱った機能を説明する際、読者が習得を実証したと主張しないでください。

完了の条件： ガイドが、導入から実例の手順まで、合意した成果を網羅していること。また、読者が次の回を待ったり、不可欠な説明を探すためにリンク先を調べたりせずに、理由をたどり、例を再現できること。

4. 確認して納品する

複数手順のセットアップ、複数ツールをまたぐ操作、コントリビューションのリハーサル、または環境によって結果が変わる作業を含むガイドでは、利用可能で、セットアップに見合う価値がある場合、独立した読者による再実行を行います。担当を割り当てる前に独立した再実行を読んでください。短い文章の修正や概念だけの説明で、必ずしも作業者を割り当てる必要はありません。著者自身による実行は引き続き必要です。独立した再実行では、納品する資料に読者に必要な背景情報が含まれているかを確認します。

読者が申告した開始地点からガイドを読み、納品前に次の不足を修正します。

• 理解： 主要な概念について、その関係と結果が説明されていること。機能名、コマンド表、ソースへのリンクだけでは要件を満たしません。
• 理由： 重要な選択や結果に因果関係の説明があり、関連する変更例から、正確な例を超えて考える方法がわかること。
• 成果： 実例の手順が合意した到達点に達していること。コントリビューションガイドには、今後のレッスンに先送りせず、ソースに関する理由、最小限の変更、回帰テストを含めること。
• 再現性： ドキュメント中のコード例が保持されているファイルと一致し、コマンドに前提条件と作業ディレクトリが明記され、報告された結果が根拠と一致していること。修正後は、影響を受ける例を再確認します。
• 完全性： 必要な説明がすべて主文書に含まれ、ローカルリンクが機能し、根拠の限界が明確に示されていること。

ガイドと例へのリンクに加え、対象範囲と実行上の重要な制限を簡潔に記載して納品します。ワークスペースを保持し、そのために起動した一時プロセスを停止します。読者向けに意図的に稼働を続けるプロセスがあれば、その旨を記載します。読者が作業を早期に終える場合は、部分的に作成した資料と未対応の範囲を明示します。

完了の条件： 完全なガイドと例にアクセスでき、合意した範囲について上記の確認を満たし、一時プロセスの管理状況が明確になっていること。