在說明文件中加入圖表

在說明文件中，圖表可用於說明工程概念和指南。不過，請務必確保 fuchsia.dev 上的圖表可供存取及更新。本指南將說明如何在 Fuchsia 說明文件中加入可維護的圖表。

圖表類型

• 根據原始碼中的文字產生簡單的流程圖。選項：

  • Mermaid：這是一種簡單的方法，可維護從原始碼中的文字產生的圖表
  • 流程圖：使用原始碼中的文字建立基本流程圖
  • (僅限 Google 員工) go/sequencediagram：流程圖工具的內部版本

• 在 Google 繪圖、Google 簡報或其他工具中建立圖表

如何新增視覺圖表

如果您要為 fuchsia.dev 上的文件建立圖表，請按照下列步驟操作：

1. 在您選擇的工具中建立視覺化圖表，然後使用 Mermaid 等工具的程式碼區塊，或將圖片匯出為 .svg (建議) 或 .png 檔案。

   針對圖片，請務必完成下列操作：

   • 請對圖片進行最佳化，確保圖片能快速載入。大型圖片可能會增加網頁載入時間。
   • 盡可能使用 SVG (可縮放向量圖形) 格式。相較於其他圖片格式，SVG 可調整大小、可存取，且檔案大小較小。

2. 使用 Markdown 在 fuchsia.dev 上嵌入圖片。例如：查看操作說明。

   mermaid

   Markdown

   
   ```mermaid
   graph LR
   A[Square Rect] -- Link text --> B((Circle))
   A --> C(Round Rect)
   B --> D{Rhombus}
   C --> D
   ```
   
   

   html

   
   <pre class="mermaid">
     graph LR
     A[Square Rect] -- Link text --> B((Circle))
     A --> C(Round Rect)
     B --> D{Rhombus}
     C --> D
   </pre>
   
   

   已算繪：

   .svg/.png

   請務必為圖片新增替代文字。替代文字可協助螢幕閱讀器使用者瞭解圖片內容。例如：

   ![Alt text](image_filename.svg)
   

   • 將 Alt text 替換為圖片的簡短說明。
   • 將 image_filename.svg 替換為圖片的實際檔案名稱。

   例如：

   ![A flowchart showing the boot process of a Fuchsia device. The process starts
   with the bootloader, then moves to Zircon kernel, and finally to the user
   space.](component_framework.svg)
   

圖表的使用者體驗指南

圖表是實用的工具，可提供額外的說明或背景資訊，而這些資訊不易透過文字表達。有效的圖表應直接支援並強化說明文件中的文字。

• 重點：每個圖表都應有明確的重點，並傳達特定概念或想法。清楚簡潔地標示所有元素。

• 簡潔：盡量讓視覺效果清晰。避免過度複雜或視覺雜亂，以免讓讀者感到困惑。

• 一致性：在 Fuchsia 說明文件的所有圖表中維持一致的樣式和視覺語言。

• 國際化：盡量減少圖表中的文字。如果需要文字，請確保文字可翻譯及本地化。盡可能使用普遍認可的符號和圖示。

設計須知

• 視覺階層：使用清晰且一致的視覺階層，引導讀者瀏覽圖表。使用空白空間來建立視覺區隔，改善可讀性。

• 顏色：使用足夠的色彩對比，確保視障使用者能清楚閱讀內容。避免使用顏色做為傳達資訊的唯一方式。

• 可擴充性：請確保圖表可擴充，且可放大顯示而不失清晰度。

替代文字

為所有圖表提供簡明扼要的替代文字說明。替代文字應符合以下條件：

• 準確描述圖表的內容和用途
• 使用簡單易懂的語言
• 簡明扼要，避免提供不必要的詳細資訊
• 如果示意圖含有文字，請在替代文字中加入該文字

替代文字範例：

顯示 Fuchsia 裝置啟動程序的流程圖。這個程序會從引導程式開始，然後移至 Zircon 核心，最後移至使用者空間。	流程圖圖片。(過於籠統且沒有提供實用資訊)
建議做法	請勿

這張圖表說明 Fuchsia 元件架構中元件之間的關係。元件以階層方式排列，頂端為父項元件，底部為子項元件。	包含方塊和箭頭的圖表。(說明不夠詳盡)
建議做法	請勿