文件風格指南 | EmDash CMS Everything

本指南定義了 EmDash 文件的編寫方式。貢獻內容將被編輯以符合本指南。你不需要記住它——審閱者和編輯會提供協助——但遵循它會讓貢獻更快地被合併。

文件的存在是為了協助某人完成某件事，然後回到他們的專案。為疲憊、匆忙、用第二語言閱讀或剛接觸技術堆疊的讀者而寫。首先服務於那個讀者。

可讀性

優先選擇：

短句和短段落。
簡單的詞彙而非術語。
縮寫和首字母縮略詞第一次使用時寫全。
標題和清單來分隔長段落。
主動語態。

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

對於非 EmDash 主題——TypeScript、AT 協定、網頁字型、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））。

程式碼範例

程式碼範例與圍繞它們的文字一樣重要。

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

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

❌ 像這樣新增外掛程式：

引言為讀者準備程式碼做什麼，所以他們只需要弄清楚_如何_。它還為做略有不同事情的讀者建立了一個填空模式。

在 <Steps> 過程中，直接命令式指令是引言（在編號步驟中，「新增 tsconfig.json：」後跟檔案是可以的）。

其他規則：

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

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

升級和遷移指南

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

以以下內容開始：如何升級，事情可能「正常工作」但如果沒有請繼續閱讀的說明，以及指向變更日誌的連結。

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

### [Renamed/Changed/Removed/Deprecated]: <feature>

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

<一句話，現在時，它現在如何工作>。

#### 我該怎麼做？

<命令式操作：更新… / 替換… / 刪除…，使用最小的差異。>

根據讀者如何感受影響來選擇動詞。如果新的預設值替換了他們的值，那就是「Changed: default value」，而不是「Added: option」。

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

EmDash 特定內容

針對反覆出現的情況的約定，按貢獻者遇到它們的頻率排序。這是一個約定清單，不是哪些功能重要的排名。

外掛程式：沙盒化 vs 原生

沙盒化外掛程式和原生外掛程式是具有不同創作形式的不同格式。對其中一個的更改很少影響另一個。說明頁面或範例是關於哪種格式的。編輯沙盒化外掛程式頁面時，不要更改原生外掛程式範例，反之亦然。

本地化

不要在文件 PR 中包含 messages.po 更改。工作流程在合併到 main 時提取目錄。包含它們會造成混亂和合併衝突。

實驗性功能

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

Atmosphere 帳戶

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

文件是程式碼

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