openpress-diagram-drawing

open-press の図解

このスキルが担うのは、図の意味づけであり、見た目のスタイルではありません。図に何を示すべきか、図の中にどのようなテキストを含めるべきかを決定します。

基本ルール

説明ではなく、関係性を描きます。

図の本体には、空間的な意味を持つ情報のみを含められます。オブジェクト名、ポインター名、フィールド名、軸、凡例、短い状態ラベル、ノードの値、NULL、操作順序のラベルなどです。

理由、警告、例外、学習のための解説、解釈は、周囲の説明文またはキャプションに記載します。

担当範囲

• 概念に必要なのが図、表、コードブロック、説明文のどれかを選びます。
• ノード、リンク、矢印、状態、ラベル、変更前後の関係を定義します。
• 図中のテキストを簡潔に保ち、位置や方向と関連づけます。
• 図に答え、制作メモ、キャプションのような文章が含まれないようにします。

境界

• openpress は、検証・レンダリングコマンドの選択と、ソースと生成物の境界を担当します。
• openpress-create-pages は、ページ周辺の説明、キャプションの文言、ページのビジュアルスタイル、タイポグラフィ、CSS、コンポーネントの実装を担当します。
• openpress-create-slide は、スライドのビジュアルスタイル、スライドレイアウト、再利用可能な UI プリミティブ、スライドの図解を取り巻くデッキ全体のナラティブを担当します。
• openpress-create-pages は、ページベースの教材における、学習者向けの演習フローを担当します。

ワークフロー

1. 図の目的を特定します。比較、プロセスの状態、関係性のスナップショット、変更前後、操作の順序、トラバーサルの追跡、データ表現などです。
2. 表現方法を選びます。
   • リンク、所有関係、方向、状態変化には図を使います。
   • 比較項目が多い場合や追跡行が多数ある場合には表を使います。
   • 正確な構文にはコードブロックを使います。
3. まず意味をもとに描き、スタイルはそれに合わせます。
4. 図の中に説明文がなくても理解できるかを確認します。

リファレンスを読むタイミング

• リンクリスト、循環リスト、双方向リスト、スタック、キュー、多項式、スパース構造、ツリーの描画パターンについては、references/diagram-patterns.md を読みます。