文件風格指南 | EmDash CMS Everything

本指南定義了 EmDash 文件的撰寫方式。貢獻內容會被編輯以符合本指南。你不需要背誦它——審閱者和編輯會幫忙——但遵循它可以加快貢獻的合併。

文件的存在是為了幫助某人完成某事，然後回到他們的專案中。為疲憊的、趕時間的、使用第二語言閱讀的或剛接觸技術堆疊的讀者而寫。首先服務於這位讀者。

可讀性

優先選擇：

短句和短段落。
簡明詞彙而非術語。
縮寫和首字母縮寫詞第一次出現時寫全稱。
使用標題和清單分割長段落。
主動語態。

文件化如何使用 EmDash 建構，而不是EmDash 是如何建構的。實作細節僅在它改變讀者必須做出的決策時才屬於文件（何時選擇非預設值、影響其專案的注意事項）。它永遠不會替代使用範例。

對於非 EmDash 主題——TypeScript、AT Protocol、Web 字型、SQL——連結到可靠的來源而不是解釋它們。文件化某人在 EmDash 中使用該功能需要知道的內容。

應該強調什麼

頁面的重點必須由讀者完成工作所需的內容來決定，而不是由建構 EmDash 的人覺得有趣或最近才做的事情來決定。需要積極抵制的三個習慣：

撰寫新鮮感權重。 一個決定是新的，或者在作者腦海中還很新鮮，這不是突出它的理由。最常更改的東西對讀者來說很少是最重要的。按讀者需要的頻率而不是新增的時間來排列章節、清單項目和標題。如果你因為某些東西剛剛更改而文件化它，你可能在寫變更日誌條目，而不是文件。
建構者相關性高於讀者相關性。 對於做出來說重要的內部架構和設計決策，通常對於使用來說是不可見和無關的。說明讀者獲得的能力，而不是其背後的機制。定義集合的讀者不需要知道結構描述儲存在哪裡，就像他們不需要知道解析器的語言一樣。如果機制確實幫助了在 EmDash 上工作的人，它屬於內部文件，而不是面向使用者的頁面。
稻草人式自我定義。 不要透過與其他工具的漫畫形象對比來定義 EmDash（「與大多數 CMS 不同……」、「傳統 CMS 迫使你……」、「在許多 CMS 中你在程式碼中宣告 X」）。直接描述 EmDash 做什麼，讓它自己站穩。比較僅在比較是讀者自己的問題時才被允許：在評估頁面和「來自……」定向頁面上。即使在那裡也必須具體且公平——具體的行為和權衡，而不是邀請讀者不喜歡的稻草人。
透過否定來定義。 將能力框架為你_不必_做的工作——「不需要撰寫遷移」、「不需要重建」、「不需要碰程式碼」、「不需要單獨的服務」——是偽裝的稻草人：它只對攜帶你為他們發明的替代方案的讀者有效。說明讀者_做什麼_以及_發生什麼_。「在管理面板中新增欄位；立即生效」——而不是「新增欄位無需遷移、無需重建、無需程式碼」。例外是以積極方式表述的具體、與讀者相關的行為：「內容在執行階段提供，因此編輯立即顯示」是關於 EmDash 的事實；「不需要重建」是以別人不存在的痛苦來表述的同一事實——優先選擇前者。

任何句子的測試：如果刪除它，試圖完成工作的讀者是否會更糟？如果不會，刪除它。如果它只對將 EmDash 與其他東西比較的讀者有意義，那麼它在錯誤的地方或應該被刪除。

常青，而非變更日誌

面向使用者的頁面描述 EmDash 現在如何運作，面向腦海中沒有任何先前版本的讀者。沒有「現在」、「不再」、「以前」、「代替舊的」、「這已更改」。版本間差異僅存在於升級指南中。概念最近被引入永遠不是提及它是最近的理由。

聲音和語調

寫中立、事實性的句子。直接陳述事實。

✅ 外掛程式在隔離的執行階段中執行，只能存取它們宣告的 API。

❌ 外掛程式住在一個溫馨的小沙箱裡，壞事永遠不會發生！

不要使用_我們_、我們的_或_讓我們。 你不是和讀者坐在一起。改寫為直接稱呼讀者或描述系統。
永遠不要使用_我_。 文件不是關於作者的。
需要時稱呼讀者為_你_，特別是標記可能出問題的步驟時。
不要敘述或講故事。 沒有「既然我們已經設定了 X，讓我們繼續 Y」。用目標開始一個部分，然後是步驟。
避免奇思妙想、吉祥物和文化引用。 它們增加閱讀負擔且無法翻譯。
驚嘆號很少使用。 僅用於真正令人鼓舞或驚訝的事情。不確定時用句號。

標題

頁面標題是 <h1>（來自 frontmatter title）。章節從 <h2> 開始。
保持標題簡短。<h2> 和 <h3> 出現在「本頁內容」側邊欄中；預覽並縮短任何換行的內容。
不要有尾隨標點，包括冒號。
標題中的程式碼格式使用 <code>，與正文中相同。

清單

當順序不重要時使用無序清單，如一組選項或屬性。
對必須按順序執行的步驟使用有序清單。對於流程使用 Starlight 的 <Steps> 元件。
當清單項目增長為多個段落或包含多個程式碼術語時，改用 <h3> 章節。

範例

「例如」完整形式引入單個範例或假設。
括號內的「如」引入非窮舉清單（如 GitHub、GitLab）。
涵蓋每個選項的清單不是範例清單——使用不帶「如」的括號（必需屬性 (src, alt)）。

螢幕截圖

僅當螢幕截圖實質性地澄清空間關係、介面狀態或控制項位置時才使用。將說明和其他重要資訊保留在文字中，以便頁面在沒有圖片的情況下仍然可用。

每個螢幕截圖必須是最新的，並為頁面的特定目的而擷取。提供描述相關畫面和狀態的替代文字。記錄 fixture、路由、視區、地區設定和佈景主題，以便其他貢獻者可以重現擷取。

程式碼範例

程式碼範例與周圍的文字一樣重要。

用一個完整的、獨立的句子在自己的行上引入每個程式碼區塊，告訴讀者該區塊做什麼。不要以冒號結尾的句子片段、裸標題或「如下：」來引入。

✅ 以下範例在 sandboxed 陣列中註冊一個外掛程式：

❌ 像這樣新增外掛程式：

引入讓讀者準備好程式碼_做什麼_，這樣他們只需要弄清楚_如何_。它還為做稍微不同的事情的讀者建立了一個填空模式。

在 <Steps> 流程中，直接的祈使句指令就是引入（「新增 tsconfig.json：」後跟檔案在編號步驟中是可以的）。

其他規則：

使用真實、可執行的程式碼。 沒有 foo/bar。展示一個現實的設定，而不是每個可能的值——讀者只會有一個。
對任何代表檔案的程式碼區塊新增 title= 檔案名稱，以便讀者知道程式碼放在哪裡。
```
```ts title="src/plugin.ts"
```
對前後更改使用 Expressive Code 註解，而不是原始的 ```diff 圍欄。用 del={n} / ins={n} 標記更改的行，或用 del="…" / ins="…" 標記更改的文字。保持 diff 最小化且僅限於更改的行。

以下範例展示了單行更改：
```
```ts del={1} ins={2}
import { definePlugin } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";
```
```
提交前在本機預覽轉譯的程式碼。一個拼寫錯誤可能破壞顯示。

升級和遷移指南

幫助讀者將現有專案遷移到新版本的指南遵循固定結構。「我應該做什麼？」部分是讀者最重視的部分——不要吝嗇。

以以下內容開始：如何升級，事情可能「直接運作」但如果不行就繼續閱讀的說明，以及變更日誌的連結。

然後將每個破壞性更改列為自己的條目：

### [重新命名/更改/刪除/棄用]：<功能>

在早期版本中，<一句話，過去式，做了什麼>。

<一句話，現在式，現在如何運作>。

#### 我應該做什麼？

<祈使動作：更新… / 替換… / 刪除…，帶最小差異。>

根據讀者感受影響的方式選擇動詞。如果新的預設值替換了他們的值，那是「更改：預設值」，而不是「新增：選項」。

破壞性更改是需要更改讀者專案否則就停止運作的更改。給出操作，而不僅僅是事實。不是「Node.js 的最低版本現在是 X」，而是「使用以下命令檢查你的 Node.js 版本，如果低於 X 則升級」。

EmDash 特定事項

針對反覆出現的情況的規範，按貢獻者遇到的頻率排序。這是一份規範清單，不是哪些功能更重要的排名。

外掛程式：沙箱 vs 原生

沙箱和原生外掛程式是具有不同撰寫形式的不同格式。對一個的更改很少影響另一個。說明頁面或範例涉及哪種格式。編輯沙箱外掛程式頁面時，不要更改原生外掛程式範例，反之亦然。

在地化

不要在文件 PR 中包含 messages.po 更改。一個工作流程在合併到 main 時擷取目錄。包含它們會造成無謂的變動和合併衝突。

實驗性功能

實驗性旗標後面的功能，或 RFC 下的不穩定線協議格式，可能會在沒有通知的情況下更改。保持其文件簡潔，用注意 <Aside> 標記，並指向 RFC 或討論作為真實來源。不要詳盡地文件化不穩定的介面。

Atmosphere 帳戶

當 Bluesky 和更廣泛的 AT Protocol 網路背後的可攜式的、使用者擁有的身分出現時，稱之為 Atmosphere 帳戶並一致使用該術語。將第一次提及連結到 Atmosphere 登入指南或 atmosphereaccount.com。did:plc:… 和句柄是其具體識別碼；在需要字面值的地方使用它們。

文件就是程式碼

文件站台是一個與 EmDash 相鄰的 Astro 專案。文件更改經歷與程式碼相同的拉取請求和審閱流程。每個文字更改都等待審閱；措辭更改可能會改變句子的含義或需要在站台其他地方進行匹配的編輯。小的、經過審閱的、一致的更改保持整個站台的連貫性。