撰寫散文
這些規則適用於 Markdown 文件以及任何程式碼中的文件註解。標示為「僅限 Markdown」的規則不適用於文件註解。在文件註解中，應遵循其程式語言的慣例，例如 Go 的 [Name] 文件連結。特定類型文件（如 ADR 與詞彙表）的技能會在這些規則之上新增自己的規則。
語氣
放鬆但精確。以經驗豐富的工程師向另一位工程師解釋主題的方式進行寫作。避免過於正式的規格語言。偏好清晰、自然的解釋，同時保持技術準確性。語氣應親切且適合對話，但不至於隨意。
假設讀者對軟體開發有中等程度的理解，但可能不熟悉 Dogmatiq 專案或文件的領域。避免使用術語，並解釋文件所需的任何技術詞彙。將讀者想像成一位擁有約五年專業經驗的應用程式開發者，熟悉 Go，但對演算法或數學背景知識較少。
檔案名稱（僅限 Markdown）
使用小寫檔案名稱，例如 glossary.md，除非外部慣例有不同要求，例如 LICENSE 或 README.md。
換行（僅限 Markdown）
重新排列每個段落，使每行在 80 個字元內盡可能容納最多單詞。
標點符號
- 在散文中使用直引號與撇號（
"、'），切勿使用彎引號。非 ASCII 字元在程式碼區塊與公式中可以使用。 - 寫作 em dash（長破折號）時，兩側各留一個空格，例如
word — word。 - 使用 em dash 作為插入語分隔符，而非連字號。
- 在列表與段落中，使用 em dash 來表示定義術語的同位語。不要使用冒號、分號或括號來表示。
- 考慮重構包含多個 em dash 的句子或段落。
- 謹慎使用分號，僅用於對比（A；B 不這樣）、修飾（A；然而 B）或邏輯結果（A；因此 B）。如果子句自然適合分開成兩個句子，則優先使用句號。
- 將散文中的雙連字號（
--）替換為適當的 em dash。否則，建議使用正確的標點符號。
拼寫
使用美式英語。如有疑問，請參考 go.dev、Go 標準函式庫文件，或 AWS 與 GCP 文件。
| 美式（正確） | 非美式（錯誤） |
|---|---|
| analyze | analyse |
| behavior | behaviour |
| canceled | cancelled |
| center | centre |
| color | colour |
| initialize | initialise |
| labeled | labelled |
| serialize | serialise |
參考連結（僅限 Markdown）
- 使用參考式連結，切勿使用內嵌連結。
- 將連結定義放在檔案底部，以標籤式的 HTML 註解進行分組，例如
<!-- references -->或<!-- anchors -->。 - 每一組依標籤字母順序排序。例外情況是
CHANGELOG.md中的版本連結，應保持版本升序，因此[0.9.0]在[0.10.0]之前。 - 當連結的詞彙出現複數形式時，請新增一個複數形式的定義，例如
[instructions]: #instruction，以使原始文字讀起來自然。 - 每個定義必須至少使用一次。刪除未使用的定義。
- 每個參考必須有對應的定義。不要留下中斷的參考。
審閱
對照上述每一條規則檢查文字。對於每個問題，引用問題文字、指出其違反的規則，並建議修正方式。