sentenz/technical-article

技術文章

指導 AI 代理以正式語言、連貫結構、精確術語、實務範例及可驗證參考文獻，來建立、修訂與審閱技術文章。

• 1. 優點
• 2. 原則
  • 2.1. 語言
  • 2.2. 內容完整性
• 3. 結構
  • 3.1. 檔案與標題
  • 3.2. 前言
  • 3.3. 目錄
  • 3.4. 編號章節
  • 3.5. 分類法與定義
  • 3.6. 範例與資料
  • 3.7. 參考文獻
• 4. 工作流程
  • 4.1. 建立
  • 4.2. 修訂
  • 4.3. 審閱
• 5. 樣式指南
  • 5.1. 語氣與語調
  • 5.2. 術語
  • 5.3. 句子與段落
  • 5.4. 清單與引用
  • 5.5. 連結與引用
  • 5.6. 程式碼、表格與提示框
• 6. 品質門檻
• 7. 資源
• 8. 參考文獻

1. 優點

• 一致性

  穩定的文章語法使技術內容在不同主題間保持一致，讓讀者無需重新學習文件結構即可找到定義、分類、原則、範例及參考文獻。

• 可讀性

  簡潔的定義段落、明確的標題及術語定義清單，可在保持技術精確性的同時降低認知負擔。

• 可導航性

  手動維護的階層式目錄與編號標題，能展現概念階層，並為較長的文章提供直接導航。

• 重複使用性

  分類法、術語清單、實務範例與標註的參考文獻，使每篇文章既可作為入門介紹，也可作為耐用的工程參考資料。

• 可審查性

  確定的格式化與證據規則，允許審查者區分結構缺陷、語言缺陷與技術不準確之處。

2. 原則

2.1. 語言

• 正式

  使用適合軟體工程師、系統工程師、安全專業人員及技術決策者的中性用語。

• 百科全書式

  在規範實務之前先定義主題。在提出建議前，先解釋概念是什麼、如何分類以及在何處應用。

• 精確

  優先使用領域特定的名詞與動詞，避免寬泛或推銷性質的措辭。區分標準、規格、協定、工具、框架、實務、指標及架構模式。

• 非個人化

  優先使用第三人稱或非人稱結構。避免第一人稱敘述、直接的第二人稱稱呼、反問句及對話式的填充詞。

• 陳述式

  直接陳述定義、關係、約束與結果。僅在表達實際需求、建議、可能性或不確定性時使用情態動詞。

2.2. 內容完整性

• 證據

  以權威來源支援外部可驗證的陳述。優先使用標準制定機構、官方文件、原始研究及權威儲存庫。

• 時效性

  在納入具時效性的事實、特定版本的行為、效能閾值、法律要求及產品能力之前，先進行驗證。

• 範圍

  將每篇文章集中在一個技術主題上。連結至相鄰文章，而非大量複製背景資料。

• 分類一致性

  每次僅根據一個明確的分類維度來分組概念。除非章節說明了其中的關係，否則不要將工具、實務、結果與屬性視為同級項目。

• 範例

  使用語法正確、技術上合理且與前述解釋直接相關的範例。

3. 結構

3.1. 檔案與標題

• 檔案名稱

  使用小寫的 kebab-case 檔案名稱來識別主題，例如 technical-debt.md、feature-flags.md 或 file-systems.md。

• Frontmatter

  除非目標儲存庫明確要求，否則不要在文章檔案中新增 YAML frontmatter。

• H1 標題

  以一個包含主題官方名稱（使用 Title Case）的 H1 標題開頭。

  # Feature Flags
  

3.2. 前言

緊接在 H1 標題之後，放置一至兩個簡潔的段落。

1. 定義

   在第一句中定義主題。當縮寫在文章領域中並非普遍自明時，應在首次使用時展開。

2. 背景

   解釋主題的目的、操作角色或與軟體工程的關係。在目錄之前不要引入詳細的分類法。

範例：

# Feature Flags

Feature flags are runtime controls that enable or disable application behavior without requiring a new deployment. They decouple code deployment from feature release and support controlled rollout, experimentation, and operational mitigation.

3.3. 目錄

在前言之後、第一個 H2 章節之前，插入手動維護的 Markdown 目錄。

• 階層

  使用每層兩個空格的縮排，鏡像出每個編號的 H2、H3 及重要的 H4 標題。

• 標籤

  包含完整的數字前綴與標題文字。

• 錨點

  使用 GitHub 相容的小寫錨點。根據 GitHub 標題規則移除標點符號，同時保留單字間的連字號。

• 完整性

  每當標題有新增、移除或重新命名時，一併更新目錄條目。

範例：

- [1. Category](#1-category)
  - [1.1. Deployment Strategies](#11-deployment-strategies)
    - [1.1.1. Blue-Green Deployment](#111-blue-green-deployment)
    - [1.1.2. Canary Deployment](#112-canary-deployment)
- [2. Principle](#2-principle)
- [3. Best Practice](#3-best-practice)
- [4. Terminology](#4-terminology)
- [5. References](#5-references)

3.4. 編號章節

在 H1 以下的每個文章標題中使用阿拉伯數字十進制編號。

• H2

  使用 ## 1. <Section> 表示頂層章節。

• H3

  使用 ### 1.1. <Subsection> 表示第二層章節。

• H4

  僅在子章節包含需要另一層級的大量分類法時，使用 #### 1.1.1. <Topic>。

• 深度

  包含 H1 在內，偏好不超過四個標題層級。以術語定義清單或表格取代過深的標題層級。

• 標準章節

  僅選擇有助於主題的章節。常見且與文集相容的標籤包括 Benefits、Category、Principle、Principles、Best Practice、Terminology 及 References。

• 順序

  從基礎概念與分類開始，接著介紹原則或實務，最後以術語與參考文獻結尾。

3.5. 分類法與定義

使用散文進行概念過渡，並使用術語定義清單來呈現易於掃讀的技術內容。

• 章節引言

  以一至兩個段落開啟一個主要章節，說明分類維度或該章節的目的。

• 術語定義模式

  以條列項目呈現技術標籤，並以縮排的引用區塊呈現其解釋。

  - Atomicity
    > Atomicity ensures that a transaction completes as one unit or rolls back without retaining a partial result.
  

• 分組模式

  當一個子章節包含數個不同的觀點（例如慣例、範例或工具）時，使用有序清單項目作為局部組標題。

• 標籤大小寫

  概念標籤使用 Title Case，描述則使用 Sentence case。

• 描述品質

  以該詞項的角色、行為或定義屬性作為描述的開頭。避免迴圈定義（重複標籤而未增加意義）。

3.6. 範例與資料

• 獨立範例

  使用 Example: 來介紹散文層級的獨立範例。在分組的子章節（例如 Examples and Explanations）中，則改用描述性的範例標籤。

• 程式碼範例

  使用帶有最準確語言標識符的圍欄程式碼區塊。

• 行內語法

  對於命令、檔案路徑、配置鍵、識別碼、字面值及簡短語法片段，使用反引號。

• 表格

  使用 Markdown 表格來呈現緊湊的比較、矩陣、指標、命令或列舉的參考資料。保持儲存格內容平行，避免在儲存格內放置散文段落。

• 圖表

  當關係或流程無法以散文或表格有效解釋時，使用基於文字的圖表，例如 Mermaid。

• 提示框

  謹慎使用 GitHub 提示框，用於約束、注意事項、交叉連結或會實質改變解讀方式的資訊。

  > [!NOTE]
  > The metric threshold depends on the cited reporting period and must be verified before publication.
  

3.7. 參考文獻

每篇文章以一個編號的 References 章節結尾。

• 內部參考文獻

  使用相對於儲存庫的連結，指向相關的 Sentenz 文章。

  - Sentenz [Versioning](../articles/versioning.md) article.
  

• 外部參考文獻

  在連結標題之前註明組織或發行者名稱，並在連結之後標明來源類型。

  - NIST [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) publication.
  - Kubernetes [Documentation](https://kubernetes.io/docs/) documentation.
  - GitHub [DORA Four Keys](https://github.com/dora-team/fourkeys) repository.
  

• 來源類型

  使用精確的限定詞，例如 article、documentation、page、publication、repository、report、specification 或 standard。

• 相關性

  僅納入在文章中引用或實質使用的來源。不要建立與文章主張無關的一般閱讀清單。

4. 工作流程

4.1. 建立

1. 檢查

   閱讀目標文章目錄中的相鄰檔案。記錄當地的標題詞彙、連結樣式、程式碼圍欄慣例及相關的內部文章。

2. 範圍

   定義文章的主題、預期深度及主要分類維度。將相鄰的主題分離到交叉連結的文章中。

3. 研究

   收集權威的主要來源。驗證術語、標準、指標、產品行為及具時效性的細節。

4. 大綱

   在起草散文前，選擇所需的標準章節，並建構編號標題階層。

5. 載入模板

   建立新文章時，載入 assets/technical-article-template.md。移除對該主題無貢獻的章節。

6. 起草前言

   撰寫 H1 標題及一至兩個定義段落。建立主題與工程背景，不要在前端堆疊實作細節。

7. 建立目錄

   鏡像出規劃的標題階層，並產生精確的 GitHub 相容錨點。

8. 撰寫章節

   僅在能增進理解之處，新增章節引言、術語定義清單、範例、表格、圖表及提示框。

9. 新增參考文獻

   新增內部相對連結及外部標註來源的參考文獻。確保每項重要的外部陳述都有適當的權威來源。

10. 驗證

    在返回或提交文章之前，套用所有品質門檻。

4.2. 修訂

1. 保留意圖

   在改變結構之前，先識別現有文章的主題、範圍與分類法。

2. 載入模板

   在修訂文章之前，載入 assets/technical-article-template.md。將其作為結構基準，移除不適用的模板章節，並保留有效的文章特定章節。

3. 診斷

   將缺陷區分為技術準確性、分類法、組織、語言、格式化、連結、範例及參考文獻。

4. 標準化

   使標題、前言、目錄、編號、標題層級、清單、引用區塊、程式碼圍欄及參考文獻與此技能保持一致。

5. 改進語言

   用直接的技術定義與領域適當的動詞，取代模糊、重複、對話式或推銷性質的措辭。

6. 協調導航

   在每次變更標題或檔案名稱後，更新錨點、交叉連結及參考文獻。

7. 驗證

   重新執行所有品質門檻，並確認修訂未在沒有明確理由的情況下移除技術相關資訊。

4.3. 審閱

1. 載入模板

   在審閱文章之前，載入 assets/technical-article-template.md。將其作為結構基準，除非省略選擇性章節會造成完整性或一致性的問題，否則不要將其報告為缺陷。

2. 評估

   按以下順序審閱文章：

   1. 技術正確性
   2. 範圍與分類一致性
   3. 結構符合性
   4. 術語與縮寫
   5. 範例、表格與圖表
   6. 連結與參考文獻
   7. 文法、標點符號與可讀性

3. 報告發現

   報告發現事項時，應包含受影響的標題或行號、缺陷內容、其技術後果，以及具體的修正方式。將事實錯誤與結構不一致列為優先於風格偏好。

5. 樣式指南

5.1. 語氣與語調

• 現在式

  定義、能力及目前實務使用現在式。

• 過去式

  僅在描述歷史事件或已被取代的行為時使用過去式。

• 主動語態

  當動作主體或機制重要時，偏好使用主動語態。

• 被動語態

  當過程或結果是焦點，且動作主體無關緊要時，使用被動語態。

• 非人稱視角

  避免第一人稱與第二人稱代名詞。

...

[為求翻譯效率，後續內容已省略]