explain-visually

視覚的に説明する

テキスト、例、図を使って概念を説明する HTML ページを作成します。

ソースを理解する

1. 関連するソース資料を読みます。
2. 対象読者、主旨、構成要素、順序、判断、トレードオフ、有用な次のアクションを特定します。
3. 検証済みの事実と仮定を分けます。不明な動作を作り出してはいけません。
4. 視覚化すると説明しやすい関係を選びます。

説明を構成する

答えから始めます。セクションは少数に絞ります。各セクションでは一つの要素を説明します。

具体的なタイトルを付けます。専門用語は使う前に定義します。一般的なラベルよりも、実際の名称、パス、コマンド、インターフェース、状態、観察された動作を優先します。

ソースが裏付けている場合に限り、変更前と変更後、順序、比較、階層、状態変化を含めます。読者が次にすべきことを示して締めくくります。要約を繰り返してはいけません。

成果物を作成する

• ユーザーが別の構成を求めていない限り、自己完結型の HTML ファイルを一つ作成します。
• セマンティック HTML、インライン CSS、インライン SVG を使用します。プロジェクトで既に提供されている場合、またはユーザーが求めている場合を除き、実行時の依存関係は避けます。
• 主題に合った色、フォント、レイアウトを選びます。デフォルトで同じ配色、フォントの組み合わせ、ダッシュボード、スライドテンプレートを使い回してはいけません。
• レスポンシブな文字サイズと余白を使います。モバイルでは、デスクトップのアスペクト比を維持するのではなく、セクションが自然に広がるようにします。
• フロー、関係、状態、アーキテクチャには SVG を使います。比較、タイムライン、カード、注釈付きの例には HTML と CSS を使います。
• ラベルは短くし、説明を図のそばに配置します。
• 構成要素が三つ以上ある場合は、図を段階的に作成します。前の状態を描き直し、コンポーネントを一つずつ追加します。
• 入力を変える、状態を表示する、二つのケースを比較するなど、説明に役立つ場合に限りインタラクションを追加します。
• コントロールはキーボードで操作できるようにし、意味のある図にはテキストによる代替表現を用意します。

ソース資料の説明に役立たない限り、グラフ、グラデーション、アイコン、アニメーションを追加してはいけません。

確認する

利用可能な実ブラウザーまたはレンダラーで成果物を開き、デスクトップ幅と狭いモバイル幅で確認します。

以下を確認します。

• テキストが切れたり、重なったり、はみ出したりしていない
• どの画面幅でも文字と図のラベルが読みやすい
• フォーカス状態が見え、コントロールをキーボードで操作できる
• 十分なコントラストがあり、アニメーションがある場合は動きを抑える設定にも対応している
• コンソールエラー、アセットの欠落、ネットワークリクエストの失敗がない
• すべての事実に関する記述がソースで裏付けられている

不具合があれば、ファイルを返す前に修正します。ブラウザーまたはレンダラーを利用できない場合は、レイアウトを検証していないことを明記します。

成果物へのリンクと、ソース、および確認した画面幅を記した短いメモを返します。作成手順は説明しません。