nasa-handbook

NASA ハンドブックのページ

このスキルでは、1969年のアポロ運用ハンドブックのページを思わせる、1ページ（または数ページ）の技術文書を作成します。タイプされた柱が番号付き段落の上に置かれ、その下にメインの線画、2つ目の図、データ表、注意書き、乗組員用チェックリストが続きます。小口のタブと日付入りのフッターでページを仕上げます。実際の題材（コードベース、製品、プロトコル）にも、架空の題材（ポータルガン）にも適しています。実際の題材では、技術的な考え方を読者が理解できるページにします。架空の題材では、説得力のあるページにします。

完成したページはスキルに含まれています。作業を始める前にPNGを確認してください。これが基準です。

• assets/examples/portal-gun-device.png（および .html）：架空の装置です。引き出し線、寸法、断面図を含む全体配置図、電気回路図、そして淡々としたWARNINGがあります。
• assets/examples/espresso-fluid-system.png（および .html）：実際の物理法則（あ月面居住施設の船室圧力での抽出）に基づいた架空の機械です。断面図付きの全体配置図、ステーションタグ付きの流体・電気回路図、計算で作成したグラフがあります。新しいエージェントが、このスキルだけを使い、6回のレンダリングで作成しました。

リソースパス

以下のパスは、このスキルのディレクトリ（スキルの読み込み時に報告されるベースディレクトリ）からの相対パスです。

• assets/template.html：すべてのCSS、共通のSVGマーカーとパターン、各ブロックのひな形、収まり具合の確認機能を備えたページです。ページは必ずここから作成してください。
• assets/fonts/：Routed Gothic（Leroyレタリング）、Letter Gothic、およびそれらのライセンスです。このフォルダーをページの隣にコピーしてください。
• scripts/render.sh：ヘッドレスChromeでPDF（印刷用）と2倍サイズのPNG（プレビュー用）をレンダリングします。フッター上部に残された余白を表示し、ページがはみ出すと終了コード3で終了します。
• scripts/check.py：ページが1ページであること、ページサイズ、白黒のみであること、フォントを確認します。また、目視確認用に幅が半分のタイルを300 dpiで切り出します（出力先を指定するには --out DIR を使います）。はみ出しは検出できません。検出には render.sh を使ってください。
• references/style-guide.md：構成、スペースの配分、タイポグラフィ、文章の文体、描く図の種類、作図の作法、落とし穴、バリエーションを説明しています。セッション内で最初のページを作る際は、全編を読んでください。
• references/svg-parts.md：コピーして貼り付けられる作図パーツ（ボックス、ドラム、配線、遮断器、スイッチ、トークバック、引き出し線、寸法、断面図、タイムライン、シーケンス、部品ストリップ、バルブ、ポンプ、計器、センサー、ステーションタグ、グラフ）。
• references/sources.md：スキャンした原資料と、そこから得られた知見です。

ワークフロー

1. 対象を理解し、核となるアイデアを一つ見つけます。 読者に持ち帰ってもらうべき一文です（「コーヒーは密閉回路内で、海面気圧のもと抽出される」）。実在するシステムの場合は、仕様書または README とコードを読みます。記載する予定の数値（上限、サイズ、間隔、再試行回数、キー割り当て、UI 文字列）をすべて grep し、ドキュメントと食い違う場合はコードを優先します。架空の対象の場合は、まず一貫した仕様を考えます。名称、機能、単位付きの数値を 5～8 個、操作方法、そして危険な故障モードを一つ決めます。

2. 描画する前に、紙の上でページを設計します。 ブロックの順序を決めます。導入（3 行）、メイン図、機能の説明（4 行）、下線付きのメカニズムを一つ（2 行）、補助図（DETAIL の拡大図は任意）、データ表（6～8 行）、注意書き一つ、チェックリスト（6～7 ステップ）です。スタイルガイド §5 の表から図の種類を選びます。本文は先に書きます。短い文章を書くことで、図で何を説明すべきかが明確になります。

3. フォルダーを用意します。 ユーザーが指定したフォルダーを使います。指定がなければ、現在のプロジェクトまたは作業ディレクトリに新しいフォルダーを作成します。

   mkdir -p <out> && cp <skill>/assets/template.html <out>/<name>.html && cp -R <skill>/assets/fonts <out>/fonts
   

4. テンプレートを埋めます。 [BRACKETED] のプレースホルダーをすべて置き換えます。svg-parts.md のパーツを使い、ミリメートル座標で図を描きます。共通の nh-* defs はそのまま使います。色、ロゴ、テクスチャは追加しません。

5. レンダリングして収めます。 sh <skill>/scripts/render.sh <out>/<name>.html を実行します。fit: 行にフッター上部の残りのスペースが表示されます。4～10 mm を目安にします。はみ出すと終了コード 3 で終了します。その場合は文字サイズではなく、文章を削るか表の行を一つ減らします。下段では、高いほうの列を詰めます（スタイルガイド §2）。

6. 確認して見た目をチェックします。 uv run --no-project --with pymupdf python <skill>/scripts/check.py <out>/<name>.pdf を実行します。1 ページのみで、白黒だけであることが報告される必要があります。次に、一覧に表示されたタイルをすべて開き、以下を確認します。

   • 線や引き出し線がテキストを横切ったり、接触したりしていないか（0.6 mm の間隔を確保します）
   • ラベル同士や枠の端が接触していないか
   • 寸法値が寸法線に重なっていないか
   • 単語が切れていないか
   • 同じパターンに二つの意味が割り当てられていないか
   • 矢印が誤った対象を指していないか

   問題を修正してから、ステップ 5 と 6 を繰り返します。品質の大半はこの反復作業で決まります。3～6 回の確認を見込んでください。

7. 納品します。 PDF を印刷用ファイル、PNG をプレビューとして渡し、プレビューツールがある場合は表示します。そのページで何を説明しているかを述べます。実在する対象の場合は、数値の照合に使ったファイルを列挙します。意図的に簡略化した点があれば明記します。

適切に見せるためのポイント

説得力のあるページと、単なる仮装とを分けるのは、こうした判断です。 詳しい根拠は style-guide.md にあります。

• テクスチャより構成。 このジャンルらしさは、ランニングヘッド、番号付き段落、図のコード、変更バー、サムタブ、日付入りフッターで表現します。コーヒーの染み、ノイズ、傾いたスタンプ、NASA の徽章は省きます。
• 3 種類の書体に、それぞれ一つの役割。 本文には字間を広げたセリフ体のタイプライター文字を使います。図の中はすべて Leroy の大文字を使います。チェックリストカードに限り Letter Gothic を使います。ここでは、すべて大文字にするのがジャンルの表現であり、スタイル上の誤りではありません。
• アイデア一つ、図二つ。 メイン図で核となるアイデアを描き、補助図で時間経過に伴う挙動や詳細を示します。それ以外はすべて、この二つを補足します。
• 飾らず、正確な語り口。 三人称、現在形、単位付きの数値、銘板表記どおりの大文字の操作名、正確に引用した UI 文字列を使います。
• 線をテキストに重ねません。 引き出し線はラベルのすぐ外側から始め、対象の部品で終えます。文字を小さくするのではなく、ラベルを移動します。
• 製図に適した寸法。 線幅は 0.16～0.5 mm、矢印の長さは約 2 mm、ラベルは 2.05～2.5 mm にします。テンプレートのクラスとマーカーにはこれらがすでに設定されています。場当たり的な線を使わず、用意されたものを使います。
• 純粋な黒と純粋な白。 ハッチングと点線の輪郭で区別します。プリンターでは、色味やグレーはすべて点に変換されます。
• 実在する対象では正確さを優先。 数値が間違った、正確そうに見えるページは、表の行が一つ少ないページよりも劣ります。

バリエーション

US レター、複数ページのセクション、操作部と表示部のページ、エンジニアリング図面のシート、Technical Note の表紙、1975 年の Helvetica の外観は、すべてスタイルガイド §9 で扱っています。ページ構成、作図ルール、チェックのループは変わりません。

要件

• render.sh 用の Google Chrome または Chromium（見つからない場合は CHROME=/path を設定してください）。
• check.py 用の uv（または pymupdf をインストールした Python）。
• Iowan Old Style は macOS に付属しています。それ以外の環境では、本文フォントは Georgia にフォールバックしますが、問題ありません。Helvetica Neue（または Arial）は、図面ラベルにあるフラグ付きの「1」に使用されます。