visual-docs-diagrams

ビジュアルドキュメントの図解

このスキルを使って、開発者向けドキュメントにビジュアルが必要かどうかを判断し、理解しやすさ、アクセシビリティ、パフォーマンス、保守性を考慮してビジュアルをデザインまたはレビューします。

このスキルは、『Docs for Developers: An Engineer's Field Guide to Technical Writing』、特に第6章「ビジュアルコンテンツの追加」に基づいています。ガイダンスは変換して言い換えてあります。ユーザー向けの出力に書籍の文章をコピーしないでください。出典：https://link.springer.com/book/10.1007/978-1-4842-7217-6

クイックスタート

1. guidelines.md を読み込み、役立つ最小限の参考資料を選びます。
2. ビジュアルによって、読者が何を理解または実行できるようにするかを定義します。
3. タスクに基づいて、スクリーンショット、図、フローチャート、スイムレーン、またはテキストのみを選びます。
4. ビジュアルを本格的にデザインまたはレビューするには、workflows/design-technical-visual.md を使います。
5. 最終決定の前に、アクセシビリティ、パフォーマンス、配置、ソースファイル、保守性を確認します。

デフォルトの出力

ビジュアルドキュメントをデザインまたはレビューするときは、次を返します。

1. ビジュアルの目的 - 読者がより速く、またはよりよく理解すべきこと。
2. 推奨するビジュアルの種類 - スクリーンショット、ボックスと矢印、フローチャート、スイムレーン、動画、またはビジュアルなし。
3. デザイン上の注意点 - 範囲、ラベル、注釈、コントラスト、配置、形式。
4. アクセシビリティとパフォーマンスの確認事項 - 代替テキスト、キャプション、文字起こし、SVG／画像のサイズ、レスポンシブ対応。
5. 保守計画 - ソースファイル、担当者、更新のきっかけ、レビュー頻度。

目次

目的	ここから始める
ビジュアルの種類を理解する	references/core/knowledge.md
ビジュアルのルールを適用する	references/core/knowledge.md
ビジュアルの選択例を見る	references/core/knowledge.md
ビジュアルをデザインまたはレビューする	workflows/design-technical-visual.md
タスクに応じて参照先を選ぶ	guidelines.md

基本方針

• ビジュアルは文章を補足するために使い、重要な手順の代わりにしないでください。
• 1つのビジュアルにつき、アイデアまたは詳細度は1つにすることを推奨します。
• アクセシビリティと保守性は、制作後の仕上げではなく、ビジュアルデザインの一部として扱ってください。
• 動きそのものが必要で、保守も現実的な場合を除き、動画は避けてください。