画像は、ツール、処理、アーキテクチャを読者に見せるためのものです。このページでは、スクリーンショット、ダイアグラム、リファレンスダイアグラムの 3 つを扱います。画像はテキストより保守コストが高いので、目的を決めて使います。
スクリーンショットは、ソフトウェアの画面を写した画像です。ここでは主に Cloudflare ダッシュボードです。保守コストがほかのコンテンツより高いため、使う場面は絞ります。
スクリーンショットは、必要なときだけ、意図をはっきりさせて使います。たとえば、作業自体は単純でも、読者が迷いやすく、言葉だけでは説明しにくい場合に適しています。
代表例は アカウント ID とゾーン ID を確認する です。理由は次のとおりです。
- Community ↗ への SEO 流入が多い。
- 言葉だけでの説明では、混乱が解消しなかった。
- 新規利用者向けの作業で、Cloudflare の概念や操作に慣れていない。
スクリーンショットは次の条件を満たします。
- 元のアスペクト比を維持する。
- 解像度は 72dpi にする。
- 幅は 500〜600 ピクセルにする。
- 機密情報を写さない（ブラウザーで HTML を編集する必要がある場合があります）。
- サイドバーなど、頻繁に変わる画面要素は入れない。
- 内容が分かる代替テキストを付ける。
スクリーンショットは、/src/assets/images/ ↗ 配下の対応する $PRODUCT_NAME フォルダーに置きます。整理のためにサブフォルダーを追加しても構いません。
目的がはっきりしないスクリーンショットは避けます。保守が難しいためです。理由は次のとおりです。
- UI が変わっても、チームが気づかないことがある。
- 変わった内容が分かっても、特定の UI フローを参照しているスクリーンショットを探しにくい。
- 何かが変わったら、スクリーンショットを撮り直して差し替える必要がある。ダミーデータの追加や、機密情報の伏せ処理が必要になることもあります。
この保守の進め方の詳細は、画像のメンテナンス を参照してください。
ダイアグラムは、処理、アーキテクチャ、そのほかの技術を表す図です。複雑な話題を分かりやすく示し、特定のソリューション、処理、製品同士のやり取りをイメージしやすくします。どのコンテンツタイプでも使います。推奨形式は SVG ファイルまたは Mermaid ダイアグラムです。
拡大しても崩れにくいため、PNG や JPEG ではなく SVG ファイルを使います。スクリーンリーダー向けに、分かりやすい代替テキストを付けます。リポジトリ内の 定期実行スクリプト ↗ で SVG を最適化しています。
SVG は次の形式で書きます。
例:
製品や処理の流れを示すときは、Mermaid ダイアグラムを使います。用途に合うなら、検索しやすく変更しやすいため、SVG ファイルより Mermaid を優先します。Mermaid ダイアグラムは rehype-mermaid ↗ と mermaid ↗ を使っています。
Mermaid ダイアグラムは次の形式で書きます。
```mermaid
flowchart LR
accTitle: Tunnels のダイアグラム
accDescr: この例には 3 つのトンネル経路があります。Tunnel 1 と Tunnel 2 が最優先で、Tunnel 3 は予備です。
subgraph Cloudflare
direction LR
B[Cloudflare <br/> データセンター]
C[Cloudflare <br/> データセンター]
D[Cloudflare <br/> データセンター]
end
A((ユーザー)) --> Cloudflare --- E[Anycast IP]
E[Anycast IP] --> F[/Tunnel 1 / <br/> 優先度 1/] --> I{{お客様 <br/> データセンター/ <br/> ネットワーク 1}}
E[Anycast IP] --> G[/Tunnel 2 / <br/> 優先度 1/] --> J{{お客様 <br/> データセンター/ <br/> ネットワーク 2}}
E[Anycast IP] --> H[/Tunnel 3 / <br/> 優先度 2/] --> K{{お客様 <br/> データセンター/ <br/> ネットワーク 3}}
```この例の描画結果は次のとおりです。
flowchart LR
accTitle: Tunnels のダイアグラム
accDescr: この例には 3 つのトンネル経路があります。Tunnel 1 と Tunnel 2 が最優先で、Tunnel 3 は予備です。
subgraph Cloudflare
direction LR
B[Cloudflare <br/> データセンター]
C[Cloudflare <br/> データセンター]
D[Cloudflare <br/> データセンター]
end
A((ユーザー)) --> Cloudflare --- E[Anycast IP]
E[Anycast IP] --> F[/Tunnel 1 / <br/> 優先度 1/] --> I{{お客様 <br/> データセンター/ <br/> ネットワーク 1}}
E[Anycast IP] --> G[/Tunnel 2 / <br/> 優先度 1/] --> J{{お客様 <br/> データセンター/ <br/> ネットワーク 2}}
E[Anycast IP] --> H[/Tunnel 3 / <br/> 優先度 2/] --> K{{お客様 <br/> データセンター/ <br/> ネットワーク 3}}
Cloudflare のプラットフォームの全部または一部と、お客様のインフラまたはユースケースへの位置づけを、1 枚で示すダイアグラムです。
使用箇所: Reference architecture、Reference architecture diagram
特定のインフラまたはユースケースに合わせた、Cloudflare のアーキテクチャ全体を示します。可能な限り SVG にします。
例:
注: この画像のラベルは、以前の製品名を反映している場合があります。