通用寫作指南

使用 優良文件計畫 範本開發內容時，請遵循以下寫作指南。

語言和語氣

• 文件中要使用一致的語言、拼字和語氣。

• 盡可能清晰準確地描述事物。

• 使用語法檢查工具 linter 檢查文字的可讀性。

  • Grammarly 等工具可以幫助您識別文法問題

  • Vale 之類的工具可以幫助你辨識樣式問題。

  • 這篇文章 列出了其他一些程式碼檢查工具。)

• 避免使用俚語和行話，因為這會讓非英語母語者更難理解你的意思。

• 首次使用縮寫時，請務必寫出其完整拼字形式，並避免在文件中直接使用縮寫。之後可以繼續使用縮寫。

• 避免加入你自己的觀點或他人的觀點。這樣做會影響讀者從文件中得出結論的能力。

編寫程式步驟

以下是一些在建立流程步驟時可以參考的建議:

• 對於步驟繁多的流程，建議將內容 “分塊” 為每個包含 5 至 10 個步驟的小節。這樣不僅能讓資訊更易於閱讀和記憶，還能讓讀者在完成每個區塊後獲得成就感。此分段法獲得多家大型企業的推薦，例如 微軟的撰寫風格指南，以及來自尼爾森諾曼集團`關於模組和可用性的研究 <https://www.nngroup.com/articles/short-term-memory-and-web-usability/>`__。

• 每個步驟都是一個句子 (你應該能夠大聲朗讀，並且語法正確)。

• 在描述某個步驟時，要加上一句引導句，提醒讀者在按照子步驟操作時會做什麼。

• 任何一個主要步驟中的子步驟都不要超過四個。

• 如果子步驟的縮排超過一層級，請將步驟分割成一個新的主要步驟區塊。

• 子步驟過多可能意味著你需要將其中一些步驟拆分成一個新的步驟部分。

• 建議提供螢幕截圖和圖片，特別是如果您可以標註您所指螢幕的特定部分。

• 使用 可選 後面接著一個冒號來識別可選步驟。例如，

  • 可選: 請輸入典藏庫描述。

• 請使用條件子句 if (條件) then (結果) 來標示僅在特定條件成立時才適用的步驟。條件步驟應始終以條件開頭，以便不符合該條件的使用者可以跳過該步驟。例如，

  • 如果您是 Windows 使用者，請在您的電腦上安裝虛擬機器 VirtualBox 軟體。

有關編寫過程的更多訊息，請參見 Google 開發者文件樣式指南。

頁面結構

• 在開始寫作之前，先列出你想在文件中包含的標題大綱。

  • 利用提綱整理出你需要告訴讀者的主要內容。

  • 用標題來移動內容，比移動整段內容要容易得多。

• 如果主題開始出現分館，您可能還需要建立兩篇文章。

• 將你在正文中提到的所有連結加入到 “參見” 部分。文章過長時，內嵌連結容易被忽略，而且讀者需要花費更多時間查尋連結，這會增加他們的認知負擔。

標題和檔案名

• 標題應能描述文章內容。

• 確保標題在應用領域內獨一無二。

• 請確保標題和檔案名稱相同: 標題和檔案名稱不同會導致難以辨識檔案名稱。

• 標題中使用獨特的詞語，以便以後進行搜尋和替換時不會出現模糊匹配的情況。

以下是一些標題範例及其建議的檔案名稱結構:

• 使用烤麵包機

  • 使用烤麵包機.rst

• 烤一片麵包

  • 烤麵包片.rst

定義

如果在一篇長文中重複使用某些術語，可以先定義一次，然後在文章正文中重複使用。

---

探索其他指南和模板來自 優秀文件計畫。