這份文件提供 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 frontmatter，這些內容會保留在單行，不會換行。
程式碼通常會縮排 (頁面左側的空白處)，而英文散文 (說明文件) 則通常會形成文字段落。這項差異會導致寬度規格不同。
標記外部連結
使用 {:.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/- Link to documents that are in the/docs/directory of the Fuchsia source tree. 這些連結必須指向副檔名為.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。
- 大部分的 Fuchsia 參考文件並不存在於來源樹狀結構中，而是發布在 fuchsia.dev。這些連結必須做為完整網址使用。例如：
提交變更前請先測試連結
建立有效的 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
請勿在網頁和章節標題中使用反引號
請勿使用反引號 (`) 格式化網頁和章節標題中的程式碼 (#、##、### 等)。標題中的程式碼格式會不一致，導致頁面目錄和導覽混亂，並進入自動產生的錨點。在標題中以純文字撰寫程式碼字詞，並在後續內文中使用程式碼格式。
建議：在標題中以純文字形式撰寫程式碼字詞：
# BUILD.bazel files style guide
## Avoid package default_visibility
不建議：在標題中以反引號格式化程式碼字詞：
# `BUILD.bazel` files style guide
## Avoid package `default_visibility`
錨點使用破折號，而非底線
根據預設，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-terminal 執行 Shell 指令範例
建議：在殼層指令的 ``` 後方新增 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