technical-book-lab-design

技術書ラボの設計

基本的な考え方

技術書のラボは、コマンドを並べただけのものではありません。明確な開始状態、安全な手順、目に見える進捗、期待される出力、終了条件を備えた、読者を導く変化のプロセスです。読者は、何を構築したのか、なぜ動作するのか、どう検証するのか、失敗した場合に何をすればよいのかを把握できる必要があります。

このスキルは、次の設計や改善に使用してください。

• セルフホストに関する章。
• DevOps、インフラストラクチャ、プログラミング、データ、セキュリティのチュートリアル。
• 実践例や演習。
• ラボの前提条件と環境に関する想定。
• チェックポイント、期待される出力、トラブルシューティングの分岐。

参照先の案内

必要な情報	読むもの
ラボの基本概念と用語	references/core/knowledge.md
ラボ設計のルール	references/core/rules.md
変更前後の例	references/core/examples.md
ラボのレビュー用チェックリスト	references/core/checklist.md
手順に沿ったラボ設計	workflows/design-runnable-lab.md

ワークフロー

1. 読者が得られる成果を明確にする

ラボの後で読者が何を実行、判断、デプロイ、デバッグ、説明できるようになるのかを明示します。

成果が「X について学ぶ」だけの場合は、進捗を目に見える形で示せるよう、内容を具体化します。

2. 開始状態を定義する

読者がすでに持っているもの、知っていることを列挙します。

• 必要な概念。
• アカウント、ハードウェア、ソフトウェア、バージョン、オペレーティングシステム。
• ネットワーク、ドメイン、DNS、権限、認証情報、安全性に関する制約。
• ファイルやリポジトリの状態。

不足している前提条件は前の段階に移すか、簡潔にまとめるか、関連資料へのリンクを付けます。

3. 手順を設計する

ラボを小さなチェックポイントに分けて構成します。

• 各操作の前に、その目的を説明します。
• 最小限で安全なコマンドや変更を示します。
• 期待される出力や状態を示します。
• 簡単な検証方法を加えます。
• 次の判断について説明します。

4. 失敗への対処を加える

技術系の読者に必要なのは、成功する手順だけではありません。

• 起こりそうなエラーと、その意味を列挙します。
• 変更にリスクがある場合は、ロールバックやクリーンアップの手順を加えます。
• サービスの公開、権限の変更、費用の発生、データへの影響がある手順には印を付けます。
• 作業を中断して支援を求めるべきタイミングを伝えます。

5. ひととおり完了させる

すべてのラボの最後に、次の内容を含めます。

• 最終確認。
• 読者が理解しているべきこと。
• 次に安全に変更できるもの。
• クリーンアップ、保守、セキュリティに関するフォローアップ。

出力形式

ラボの設計またはレビューでは、次の内容を返します。

1. 読者が得られる成果と開始状態に関する前提。
2. チェックポイントを含むラボの手順。
3. 期待される出力と検証手順。
4. トラブルシューティング表。
5. 安全に関する注意事項とクリーンアップ。
6. 推奨する関連リソースや前提条件。

品質基準

実際の環境で実際の読者に役立つラボにします。抽象的な説明や未検証のコマンド列よりも、具体的な出力、チェックポイント、失敗への対処を優先します。