說明文件樣式指南

本文提供 Fuchsia.dev 的寫作風格指南。這些指南以 Google Developers 樣式指南的一般指南為基礎。

本指南內容：

語氣、聲音和文法

撰寫 Fuchsia 文件時，請遵守下列樣式、語氣和文法規範，確保內容清楚、一致且易於理解。

使用簡單的美國英語

使用簡單的字詞和簡潔的句子，以清楚直接的美國英語撰寫內容。 使用標準縮寫 (例如 it's、don't、you'll) 營造自然親切的語氣。避免使用非英語母語者可能難以翻譯的成語、地區俗語或俚語。

以第二人稱 (「你」) 稱呼讀者

請直接以第二人稱 (「你」) 稱呼讀者。

建議：使用第二人稱直接與開發人員對話：

You can install Fuchsia by running the following command:

不建議：請避免使用第三人稱用語 (「使用者可以」) 或第一人稱複數 (「我們可以」)：

Fuchsia users can install the OS, and then we can run the test.

使用現在式和主動語態

以現在式陳述事實和系統行為。避免使用未來式 (「將」)，以免造成動作發生時間的模糊不清。 此外，請使用主動語態而非被動語態，清楚指出執行動作的主詞。

建議：使用主動語態和現在時：

The command creates a configuration file in the working directory.

不建議：使用被動語態和未來時態：

A configuration file will be created by the command.

完整拼出縮寫字，並使用一致的術語

在文件中第一次提及縮寫字和簡稱時，請完整拼出，然後在括號中附上縮寫字 (例如「Looks Good To Me (LGTM)」)。確保技術用語與官方 Fuchsia 詞彙表一致。

大綱和導覽清單

包含頂層大綱和子章節清單

如果文件很長或有多個章節，請提供導覽清單，協助讀者掌握方向：

  • 在文件頂端附近 (簡介之後和第一個 ## 區段標題之前)，加入頂層大綱導覽清單。

  • 在主要區段 (##標題) 頂端加入子區段步驟清單，當中包含多個子區段 (###)。

確保頂層大綱不重複

頂層大綱導覽清單應只列出主要章節 (## 標題)。如果子章節已列在各自主要章節的頂端，請勿將子章節 (###) 連結巢狀化至頂層大綱的主要章節項目下方。保持頂端大綱乾淨，避免多餘內容。

選擇編號或項目符號導覽清單

只有在章節需要依序執行時，才使用編號清單項目 (1. [Section title](#anchor))，例如教學課程或使用指南。如果是循序程序，請在導覽清單前加上 "The steps are:"。

建議：循序程序的頂層大綱：

The steps are:

1. [Prerequisites](#prerequisites)
2. [Build Fuchsia](#build-fuchsia)
3. [Set up Device Cloud](#set-up-device-cloud)
4. [Troubleshooting](#troubleshooting)

如為非依序排列的主題，例如總覽、概念頁面、索引頁面或參考文件，請使用項目符號清單項目 (* [Section title](#anchor))。如果章節並非依序排列，請勿加入 "The steps are:"。

建議：非依序參照或總覽文件的頂層大綱：

* [Overview](#overview)
* [Available skills](#available-skills)

如果主要章節包含多個子章節，請在章節頂端提供子章節清單：

## Set up Device Cloud {:#set-up-device-cloud .numbered transformation="converted"}

1. [Set up environment](#set-up-environment)
2. [Check out device](#check-out-device)
3. [Recover and flash](#recover-and-flash)
4. [Serve packages](#serve-packages)

文字和連結

遵守 80 個半形字元的限制

在 Fuchsia 專案中，程式碼的行長度上限為 100 個字元，文件則為 80 個字元。所有散文行都應換行，長度上限為 80 個半形字元。

這項規則的例外狀況包括網址、參照連結定義 (例如 [reference-id]: https://...) 和頂層 YAML 前置事項，這些內容會保留在單行，不會換行。

程式碼通常會縮排 (頁面左側的空白空間)，而英文散文 (說明文件) 則通常會形成文字段落。這項差異會導致寬度規格不同。

使用 {:.external} 標記不在 fuchsia.dev、fuchsia.googlesource.com 或 fuchsia-review.googlesource.com 內的任何連結：

This is an [external](http://example.com){:.external} link.

請注意外部連結圖示：這是外部連結。

一般來說，Fuchsia 建議在 Markdown 檔案中使用參照樣式的連結。 參照樣式連結會使用與連結相關聯的參照 ID，然後在文件中使用連結時參照該 ID。這樣一來，您就能輕鬆更新文件中的連結。

建議：在您要連結的位置建立 ID。

在本範例中，連結 ID 名為 fuchsia-home：

Welcome to the [Fuchsia home page][fuchsia-home].

接著在文件底部定義：

[fuchsia-home]: https://fuchsia.dev/

不建議：撰寫內嵌連結，如下所示：

Welcome to the [Fuchsia home page](www.fuchsia.dev).

如要進一步瞭解參考樣式連結，請參閱外部的 Markdown 指南。

使用正確的連結前往不同的 Fuchsia 內容

在 Fuchsia 文件中，您可以連結至三種內容：

  • /docs/ - 連結至 Fuchsia 來源樹狀結構 /docs/ 目錄中的文件。這些連結必須指向副檔名為 .md 的檔案。例如：/docs/concepts/README.md。

  • 原始碼 - 連結至 Fuchsia 原始碼樹狀結構中的原始碼檔案。這些連結可以連結至任何副檔名，但這些檔案必須存在於來源樹狀結構中。例如：/sdk/lib/fdio/fdio.cc。

  • 參考文件 - 自動生成的 Fuchsia 參考文件連結。

    • 大部分的 Fuchsia 參考文件都不在來源樹狀結構中，而是發布在 fuchsia.dev。這些連結必須做為完整網址使用。舉例來說，https://fuchsia.dev/reference/fidl/fuchsia.io。
    • 不過，來源樹狀結構中仍有一些 Fuchsia 參考文件。這些文件位於 /docs/reference/，並發布在「https://fuchsia.dev/fuchsia-src/reference/」部分。這些連結必須連結至副檔名為 .md 的檔案。例如：/docs/reference/fidl/bindings/overview.md。

建立有效的 Markdown 文件後，請執行 doc-checker，確保文件使用有效的連結。當您嘗試提交包含 .md 檔案的變更時，Gerrit 會執行 doc-checker，如果連結失效，系統就會封鎖提交作業。

如要在本機執行 doc-checker，請使用 fx format-code 工具：

fx format-code

標頭

網頁和章節標題應採用句首字母大寫格式

所有標題和區段標題 (#、##、###) 都必須使用句首大寫。

建議：使用句首字母大寫格式。

# This title is an example of sentence case

不建議使用：使用首字大寫：

# This Title is an Example of Title Case

錨點請使用連字號，不要使用底線

根據預設，fuchsia.dev 會使用底線 (_) 取代空格來建立錨點。為章節標題建立自訂錨點時，請使用破折號 (-) 而不是底線，並使用 {#section-title} (或 {:#section-title})。此外，檔案名稱也請使用破折號。

建議：使用破折號做為錨點：

## This is a section header {:#this-is-a-section-header transformation="converted"}

請勿在網頁標題中加入自訂錨點

主要網頁標題 (第 1 階標題 #) 不需要自訂錨點。 自訂錨點只能套用至子區段標題 (##、###)。 請從 # Title 行移除所有自訂錨點 (例如 {#anchor-name})。

清單

在清單項目之間加入空白行

在項目符號清單和編號清單中，項目之間請加入空白行，方便閱讀，並確保在 fuchsia.dev 上正確顯示。此外，父項清單項目和巢狀子清單的開頭之間也請加入空白行。

建議：在項目之間和子清單之前新增空白行：

* First list item.

* Second list item.

  * First nested sub-list item.

  * Second nested sub-list item.

不建議：連續列出項目，但沒有空行：

* First list item.
* Second list item.
  * First nested sub-list item.
  * Second nested sub-list item.

註解 (附註、警告和提示)

使用支援的 DevSite 摘要語法，在 fuchsia.dev 上醒目顯示重要資訊。如要建立摘要方塊，請在段落開頭使用支援的 DevSite 摘要關鍵字，後面加上半形冒號 (:)：

  • Note: ...
  • Caution: ...
  • Warning: ...
  • Important: ...
  • Tip: ...

保持簡潔的附註方塊。附註和其他註解通常應包含單一段落或簡短句子。請勿在附註方塊內使用項目符號或編號清單。

建議做法：使用 DevSite 摘要語法，並簡潔扼要地呈現摘要內容：

Note: This is an example of a concise DevSite note callout box.

Warning: Running this command overwrites existing configuration files.

不建議：請勿在附註中加入清單，或使用系統不支援的警示格式：

  • 請勿在附註方塊中加入項目符號或編號清單。

  • 請勿使用 GitHub 樣式的引用塊警示 (例如 > [!NOTE]、> [!TIP] 或 > [!WARNING])。DevSite 不支援這些警示。

  • 請勿使用粗體或斜體開頭 (例如 **Note:** 或 _Note:_)，否則系統會將這些文字算做一般內文，而非附註方塊。

    **Note:** Do not use bolded lead-ins.

水平規則

請勿在 Markdown 文件中使用 --- 水平規則或分隔符號。 fuchsia.dev 上的章節標題 (##、###) 提供足夠的視覺分隔和結構，不需要裝飾性水平線。

程式碼範例

使用 posix 終端機執行殼層指令範例

建議：在殼層指令的 ``` 後方新增 posix-terminal，讓讀者輕鬆複製程式碼區塊中的內容。


```posix-terminal
fx ota
```

這個程式碼區塊會以指令開頭的 $ 算繪：

fx ota

不建議：請勿在指令中硬式編碼 $ 字元。

$ fx ota

停用複製功能

建議：在 ``` 後方加入 none 或 none {:.devsite-disable-click-to-copy}，表示不應複製的程式碼或輸出內容記錄範例。


```none {:.devsite-disable-click-to-copy}
$ my_command
It won't be necessary to copy and paste this code block.
```

這個程式碼區塊會顯示，但右上角不會有複製圖示：

$ my_command
It won't be necessary to copy and paste this code block.

不建議的做法：為僅供檢視的內容啟用複製功能。如果 ``` 後方未指定任何內容，系統會預設啟用複製功能。


```
$ my_command
It won't be necessary to copy and paste this code block.
```

這個程式碼區塊的轉譯結果如下：

$ my_command
It won't be necessary to copy and paste this code block.

參照原始碼時，請使用路徑而非網址

建議：凡是參照原始碼的連結，都應只參照路徑。否則會收到靜態錯誤檢查。

Update the [state header][sh]
[sh]: /zircon/system/ulib/inspect/include/lib/inspect/cpp/vmo/state.h