貢獻者百科

社群協作久了會累積許多不成文規定：標題該如何下、檔名如何命名、PR 描述要寫什麼、Issue 如何分類、新貢獻者第一週會碰到的疑問。貢獻者百科把散落在 README、Issue 留言、Matrix 對話裡的內容整合成一頁，方便新成員一次看完，也讓資深成員有共同對話的依據。

如果你是第一次參與，建議先看 如何參與與認領主題 決定方向，再回來這頁查具體做法。完整的工具入口與帳號申請見 社群自架服務。

第一週的入門路徑

依「我想做什麼」分流：

• 想試水溫，先看看內容：先讀 基礎概念 任一篇，再用 自我技能評估表 評估自己對 Tor、Tails、OONI 的熟悉度
• 想開始寫作或翻譯：申請 Matrix 帳號（見 社群自架服務）→ 加入 Public Space → 表達意願 → 認領一個 Issue
• 想參與技術維運：申請 GitHub 對 anoni-net/docs 的協作權限 → 看 專案研究預先準備 建好開發環境
• 想加入活動籌備：到 Matrix 對應 room 詢問近期活動（COSCUP、工作坊、小聚），協助文宣、現場、報名等任務

每條路徑的第一步都是「進到 Matrix 表達意願」。社群運作偏向 async，留訊息後等一兩天回覆是正常節奏。

寫作風格規範

禁用句型與標點

• 不使用 ——（雙破折號）作為句中插入語。需要補充說明時，改用冒號、逗號，或拆成兩句
  • 引用或照錄的內容不在此限：連結文字是外部來源的原始標題時保留原樣（例 [Developer mode — apps...](url)）。英文版（docs/en）的破折號屬正常英文排版，也不適用此規則
• 不使用「不是...而是...」、「不再只是...而是...」句型。改用正向直述。省略「而」、靠逗號銜接的「不是甲，是乙」也算同一個句型
• 避免用「；」斷句，優先用「。」或拆句
• 並列詞語或短語請用「、」，不要用全形「／」當列舉符號（半形 / 用在路徑、URL、技術慣用寫法）

標題句構

• 標題不使用「主題：說明」的冒號句構，改寫成一句完整的話。需要交代第二層資訊時用逗號接續，或把補述留給前言與 summary
  • Brave 抹平 GPU 指紋：一致化與隨機化在同一次更新裡分工
  • Brave 用兩種相反的手法抹平 GPU 指紋
• 文章標題與各層小標題同樣適用
• 翻譯文章照錄外部來源的原始標題時保留原樣，例：介紹 oniux：針對任何 Linux 應用程式的核心層級 Tor 隔離技術
• 既有文章不必回頭改寫，新文章與大幅改版時套用

並列引號的標點

連續的「」引號之間要加「、」。錯誤與正確對照：

• 「決策者」「被諮詢者」「需被告知者」
• 「決策者」、「被諮詢者」、「需被告知者」

段落語氣

• 像一位了解主題的社群成員在解釋，而非教科書或百科條目
• 不在每段末尾加總結句，讓段落自然收尾
• 避免「值得注意的是」、「總的來說」、「綜上所述」、「談的是」、「指的是」、「涵蓋的是」這類開頭
• 避免過度對稱的三段結構（常見 AI 寫作模式）

擬人化

非人的主體不做人的動作，四種常見情況與改法：

情況
組織說話	Brave 說之後會補上	Brave 的公告寫了之後會補上
文件說話	原文說、報告指出、文章點出風險	原文裡寫、報告的結論是、風險寫在同一篇文章
軟體有感知	網站看到不認識的字串、網站以為取得了真實資訊	網站取得的字串不在既有清單裡、網站收到的值與真實硬體無異
抽象物有意志	開關的存在說明取捨仍在、規則要做對	保留這些開關代表取捨仍在、要讓規則生效

兩種情況不在此限。組織作為行為者，動詞是實際做得出來的動作時保留原樣（Brave 推出防護、Tor Project 發布新版、OONI 蒐集量測）。直接引述照錄時，引號內保留原始說法。

標點集合

正文主要使用：「、」、「，」、「。」、「：」、「！」、「「」」、「（）」。技術術語（Tor、OONI、IP、USB 等）保持英文原文，不加引號。

精簡與去 AI 味

校稿時最常做的修法，多數是把 AI 生成痕跡與贅語拿掉：

• 刪掉開場的鋪陳句。例：把 CryptPad 的基本資料先擺出來。它由… 改成 CryptPad 由…，直接進入內容，不先宣告「接下來要講什麼」。
• 避免「這…」、「這個…」開頭，與「其實」、「換句話說」、「把它換成白話」這類填充轉折，能刪則刪。
• 「這」與「那」不要在同一句裡堆疊。同一個字在同句出現 3 次以上，或兩次中間隔不到 9 個字，就把其中一個換成它實際指的名詞，或整句重寫。例：這件事說明有人在賣這個概念，不等於這套技術已經在運作 改成 有人在賣這個概念，不等於技術已經在運作。兩個字分別計數，這份文件提到那個結論 各出現一次，不算堆疊。全文密度可以拿來抓大方向，站上每千漢字約 5 個是常態，超過 10 個的文章通常整段都要重寫。zhe-repeat 與 na-repeat 規則只掃同句堆疊，全文密度要人工判斷。
• 抽象說法改成具體內容。例：下一段會說明這個結論為什麼不準 改成 下一段的使用量資料會推翻它。
• 去掉誇飾與情緒詞。例：經過真實使用壓力 改成 有實際使用紀錄。一般詞語不必加引號強調，例：是「可被驗證的隱私」 改成 是可被驗證的隱私。
• 段落開頭不要放一句粗體的完整句子。並列的項目升成小標題，單獨一段就寫成正常句子。例：**位置。** OONI 記錄國家與 ASN… 改成 ### 位置，空一行再接內文。升成小標題後語意也更準確，那些多半本來就是子章節，順帶會進側邊目錄。粗體詞作為句子成分或清單標籤不在此限，例：**對照日**用同樣的參數、**資料來源**：…。判準是粗體內容有沒有自成一個以句號結尾的完整句子，bold-lead-sentence 規則掃的就是這個形式。

用詞與譯名

• 口語字改書面語。例：「講」改成「提到」、「說明」，「照實講」改成「不迴避」。常見的還有：

  口語	書面語
  跑（執行軟體）	依語境用執行、架設、運作、營運
  拿到	取得
  得先、得靠	需先、需仰賴
  動手	實際操作、著手、實作
  踩到	遇到
  找上門	依語境用接洽、找上、追究
  省事、省力	簡便、容易
  怎樣	副詞用「如何」，修飾語（怎樣的 X）用「什麼樣的」。「長怎樣」整句改寫，不要寫成「長如何」
  照舊	維持原狀
  差不多	相近
  掛了	無法連線
  搞錯、弄壞	出錯、損壞
  說不過去	前後不一致、於理不合
  灌爆	失真、超出範圍

  照錄他人說法不在此限。例：把讀者的感受寫成「連不上」、「跑很慢」時保留原樣，因為那正是要呈現的口吻。 - 用詞跟著臺灣走。同一個東西兩岸的說法不同時，正體版用臺灣的說法，簡體版用簡體讀者慣用的那個。

  中國慣用	臺灣慣用
  站台	網站。指這個站自己時也可以寫文件站
  網關	閘道。照錄合約或產品名稱裡的「安全網關」不在此限

• 譯名分三種處理：

  • 工具、協定、產品名保持英文原文（Tor、OONI、Tails、CryptPad）。
  • 學術或概念性名詞用中文譯名，首次出現在括號附原文，之後用中文。例：Lorenz 曲線 首次寫成 羅倫茲曲線（Lorenz curve）。
  • 機器欄位或程式內部名稱改用人類可讀說法再附原文，不要把欄位名直接丟給讀者。例：web_connectivity 寫成 網路連線測試（Web Connectivity）。

數字與編號

• 清單編號、ID、流水號用 inline code 標記，例：10006、10298，讓讀者一眼分辨那是識別碼而非一般數字。

安全與隱私寫作

匿名與隱私是這個網站的主題，寫作本身也要守住同一條線：

• 不提供可被濫用的操作配方。即使資料與 API 都公開，文章也不手把手教「全量枚舉」、「逐一抓取」這類步驟。改用結果導向的陳述，例：我們以某日為快照盤點全部清單，而非貼出枚舉所有編號的指令。
• 不揭露個別操作者的個人帳號或 handle。引用他人的觀測時用地區或角色代稱，例如把某個真實帳號代稱為 泰國觀測者，只在當事人公開且必要時才具名。
• 涉及受害者、未公開研究、個資的內容，走上傳機敏資訊流程。

檔案命名與目錄

檔名

• 全部小寫，使用連字號分隔（tor-browser-advanced.md、anonymity-vs-privacy.md）
• slug 以英文為主，避免中文檔名
• 縮寫保持小寫（vasp-2026.md 而非 VASP-2026.md）

目錄結構

文件站的目錄結構維持扁平，不再加深層子目錄。新文章放進現有的 7 大分類：

分類	內容性質
basics/	概念層，匿名與隱私的核心思考工具
tools/	工具層，具體的工具介紹與比較
scenarios/	場景層，特定角色或情境的應用
advanced/	進階層，技術深度的延伸閱讀
taiwan/	在地脈絡，台灣的法規、觀測、研究
reports/	嚴選報告，外部研究的中譯
community/	社群文件，治理、流程、入口頁

如果你的新文章不確定該放哪一類，先在 Matrix 上問一聲，避免直接 PR 後又要搬。

搬檔、改名、刪頁要補 redirect

移動、改名或刪除已上線的頁面時，在同一個 PR 補上 redirect，讓舊網址不會變成 404。舊網址會長期活在搜尋引擎、書籤與外部連結裡，少了 redirect 就流失既有讀者與累積的 SEO 權重。

• redirect 寫在三支 mkdocs 設定的 plugins.redirects.redirect_maps：mkdocs.yml 對應 zh-TW（/docs/）、mkdocs_en.yml 對應 en、mkdocs_cn.yml 對應 zh-cn。
• 格式是「舊路徑: 新路徑」，路徑相對各語系的 docs 目錄，不含 docs/<lang>/ 前綴。例：'tools/what-is-ooni.md': 'tools/index.md'。
• 找不到一對一的新頁時，導向所屬分類的 index 頁（community/index.md、tools/index.md 等）。
• 既有 redirect 保留不刪，舊網址會一直有人點進來。唯一要回頭改的情況：某條的目標頁自己也被移掉，redirect 變成斷鏈。

拆頁或搬走段落要回頭檢查入口連結

redirect 管不到內容搬移。頁面留著、只有其中一段被拆到新頁時，舊網址仍然回 200，沒有任何工具會報錯，但指向舊頁的按鈕與連結承諾的東西已經在別處。

• 拆頁或把段落搬到別頁時，在同一個 PR 內搜尋站內指向來源頁的連結，把文案提到搬走內容的那幾條重新指向新頁。
• strict build 與 docs-style-lint 都抓不到這種錯。兩個目標檔都存在，錯的是連結語意而非能不能連，只有讀按鈕文案對照目的地才找得到。
• 已發布的 blog 文也算在內。按鈕是功能性入口，讀者點它是要找那份內容，重新指向不等於改寫文章當時的記述。

實例：2025-05 把工作坊頁拆成兩頁時，event-workshop-2025.md 留下活動資訊，招募與籌備內容搬到 event-workshop-2025-prepare.md。兩篇 2025-04 的貼文有「查看工作坊招募頁面說明」與「瞭解籌備事項」兩個按鈕仍指向活動頁，到 2026-08 才被發現。

圖片與資源

• 圖片放在 docs/zh-TW/assets/images/
• 在 markdown 引用：對於 basics/、tools/ 等深度 1 的目錄，用 ../../assets/images/檔名
• 對於 reports/interseclab-network-coup/ 等深度 2 的目錄，用 ../../assets/images/檔名（剛好一樣）
• 截圖優先使用 webp 或最佳化過的 png，不直接放手機原始大檔
• 圖片如果有 lightbox（點擊放大），HTML 用 <figure> + <a href> 包 <img>，兩個的相對路徑都要對齊

跨檔連結規則

內部連結用相對路徑，不要寫成 /docs/zh-TW/... 絕對路徑：

• 同一目錄：./other-file.md 或直接 other-file.md
• 跨目錄：../basics/anonymity-vs-privacy.md
• 跨深度：../../blog/posts/2025to2026.md

需要寫對外完整網址時（社群貼文、外部引用），網站預設語系 zh-TW 不帶語系區段：docs/zh-TW/community/i18n.md 對應 /community/i18n/。zh-CN 用小寫 /zh-cn/...，en 用 /en/...。資料夾路徑仍保留語系大小寫。

文章末尾建議放「接下來」、「相關閱讀」之類的小節，連結到 2–4 篇相關文章。基礎、工具、場景、進階之間的橫向連結比單向引用更有用。

PR 流程

Branch 命名

• blog/<short-slug> 處理 blog 文章（例：blog/throttle-drill-results）
• feat/<short-slug> 處理新功能、新分類、寫作規範，以及既有文件的大幅改寫（例：feat/title-colon-rule）
• fix/<short-slug> 處理 bug、樣式與小幅修正（例：fix/table-width）

docs/ 不能當前綴。docs 本身是建置觸發分支，git 不允許同一個名稱同時是 ref 與 ref 的目錄，git switch -c docs/vasp-2026-rewrite 會回報 cannot lock ref。

Commit 訊息格式

採用 conventional commits：

<type>(<scope>): <subject>

<body>

常用 type：docs、feat、fix、chore、refactor。scope 用語系或子專案名稱（zh-TW、zh-CN、en、pulse、asn_coverage）。

PR 描述

PR 描述至少包含：

• 改動的「為什麼」（連結 Issue 或社群討論）
• 改動的範圍（哪些檔案、哪幾個段落）
• 對讀者的影響（連結是否會壞、URL 是否變更、有沒有相依的檔案要一起改）

Review

• 翻譯、文字校對：請求至少一位非作者 review
• 結構性變動（搬檔、改 nav）：先在 Matrix 提案討論，再開 PR
• 圖片、資源：自我檢查 alt 文字、檔名、版權標示

Issue 分類

Issue 標籤體系（持續調整中）：

• type:docs 文件相關
• type:bug 行為錯誤
• type:enhancement 改進建議
• type:question 問題討論
• area:zh-TW / area:zh-CN / area:en 語系區分
• area:tools / area:scenarios 等對應分類
• good first issue 給新貢獻者的入門 Issue
• help wanted 需要更多協助的 Issue

開 Issue 前可以先在 GitHub 搜尋既有 Issue，避免重複。

翻譯流程

zh-TW 是 single source of truth，zh-CN 與 en 從 zh-TW 同步。詳細流程見 中文化與文件翻譯：

• 新文章預設先寫 zh-TW
• zh-CN 用工具輔助初翻 + 人工調整詞彙差異（用語、慣用詞）
• en 需要更多人工，因為文化脈絡轉換比語系翻譯費時
• zh-CN 與 en 的翻譯不必同步上線，依社群人力滾動處理
• 校對時要抓「翻漏」，也就是 zh-TW 具名的國家、公司、機構、法條、數字在譯文被換成上位詞。判準與檢查方式見 校對時要抓的是翻漏

提問前先看哪裡

新貢獻者最常問的問題與對應出處：

問題	看這裡
如何選擇主題開始？	如何參與與認領主題
如何申請 Matrix 帳號？	社群自架服務
我的程度適合做什麼？	自我技能評估表
如何設定開發環境？	專案研究預先準備
翻譯有什麼規範？	中文化與文件翻譯
緊急情況的對外資源？	緊急求救

如果上述都沒答案，到 Matrix 詢問。詢問前盡量提供：你想做什麼、你已經試過什麼、你卡在哪。

行為準則摘要

社群以開放、互助、合法為原則。以下是快速摘要，完整版（含角色定義、決策流程、爭議處理）見 治理章程，兩者不一致時以治理章程為準。重點：

• 互相尊重：不同背景、不同熟悉度的成員一視同仁
• 討論議題不攻擊個人：對事不對人
• 合法前提：所有討論與協作以合法用途為前提，不協助洗錢、規避稅務、騷擾、跟蹤、未授權入侵等行為
• 資訊揭露：涉及個人資料、機敏資訊的處理走 上傳機敏資訊流程
• 爭議處理：先在 Matrix 討論，沒有共識可提案到下一次社群同步討論

違反原則的行為會由核心成員依治理章程處理。

這份百科是活文件

新貢獻者遇到本頁沒有涵蓋的問題、發現某個流程其實沒寫清楚，歡迎提案修改本頁。改 contributor-handbook 本身就是一個 good first issue 的好題目。