技术文章
为 AI 代理提供创建、修订和审查技术文章的指南，要求使用正式语言、连贯结构、精确术语、实用示例和可验证的参考文献。
1. 好处
-
一致性
稳定的文章语法使技术内容在不同主题间具有可预测性，读者无需重新学习文档结构即可快速定位定义、分类、原则、示例和参考文献。
-
可读性
简洁的定义性段落、明确的标题和术语-定义列表在保持技术精度的同时降低了认知负荷。
-
可导航性
手动维护的分层目录和编号标题展现了概念层级，并为长文章提供直接导航。
-
可复用性
分类法、术语表、实用示例和限定性参考文献使每篇文章既可作为入门介绍，又可作为持久的工程参考。
-
可审查性
确定性的格式和证据规则允许审查者将结构缺陷、语言缺陷和技术不准确性分开处理。
2. 原则
2.1. 语言
-
正式
使用适合软件工程师、系统工程师、安全专业人士和技术决策者的中性英语。
-
百科全书式
在提出实践建议之前先定义主题。先解释一个概念是什么、如何分类、应用于何处，然后再提出建议。
-
精确
优先使用领域特定的名词和动词，避免宽泛或宣传性的措辞。区分标准、规范、协议、工具、框架、实践、指标和架构模式。
-
非人称
优先使用第三人称或非人称结构。避免第一人称叙述、直接的第二人称称呼、反问句和会话式填充语。
-
陈述式
直接陈述定义、关系、约束和结果。仅在表达实际要求、建议、可能性或不确定性时使用情态动词。
2.2. 内容完整性
-
证据
使用权威来源支持可外部验证的主张。优先选择标准机构、官方文档、原创研究和权威仓库。
-
时效性
在包含时间敏感的事实、特定版本的行为、性能阈值、法律要求和产品能力之前进行验证。
-
范围
确保每篇文章聚焦一个技术主题。链接到相邻文章，而非复制大量背景材料。
-
分类连贯性
一次只按一个明确的分类维度对概念进行分组。除非章节解释了关系，否则不要将工具、实践、结果和属性作为同级内容混用。
-
示例
使用语法有效、技术上合理且直接与前面解释相关的示例。
3. 结构
3.1. 文件和标题
-
文件名
使用小写 kebab-case 文件名来标识主题，例如
technical-debt.md、feature-flags.md或file-systems.md。 -
前言
除非目标仓库明确要求，否则不要在文章文件中添加 YAML 前言。
-
H1 标题
以一个 H1 标题开始，其中包含使用标题大小写的规范主题名称。
# 功能标志
3.2. 引言
在 H1 标题之后立即放置一到两个简短的段落。
-
定义
在首句中定义主题。当缩写在文章领域内并非普遍不言自明时，在首次使用时展开。
-
上下文
解释主题的目的、操作角色或与软件工程的关系。在目录之前不要引入详细的分类法。
示例：
# 功能标志
功能标志是一种运行时控制，可以在无需新部署的情况下启用或禁用应用程序行为。它们将代码部署与功能发布解耦，并支持受控发布、实验和运营缓解。
3.3. 目录
在引言之后、第一个 H2 章节之前，插入一个手动维护的 Markdown 目录。
-
层级
使用每层两个空格的缩进，镜像每个编号的 H2、H3 和重要的 H4 标题。
-
标签
包含完整的数字前缀和标题文本。
-
锚点
使用 GitHub 兼容的小写锚点。根据 GitHub 标题规则移除标点，同时保留单词之间的连字符。
-
完整性
每当标题发生变化时，添加、移除或重命名目录条目。
示例：
- [1. 类别](#1-类别)
- [1.1. 部署策略](#11-部署策略)
- [1.1.1. 蓝绿部署](#111-蓝绿部署)
- [1.1.2. 金丝雀部署](#112-金丝雀部署)
- [2. 原则](#2-原则)
- [3. 最佳实践](#3-最佳实践)
- [4. 术语表](#4-术语表)
- [5. 参考文献](#5-参考文献)
3.4. 编号章节
在 H1 以下的每个文章标题中使用阿拉伯数字十进制编号。
-
H2
顶级章节使用
## 1. <章节>。 -
H3
二级章节使用
### 1.1. <子章节>。 -
H4
仅当子章节包含需要另一层级的实质性分类法时，才使用
#### 1.1.1. <主题>。 -
深度
包括 H1 在内，优先不超过四个标题层级。用术语-定义列表或表格替代过深的标题层级。
-
规范章节
只选择对主题有贡献的章节。常见的语料库兼容标签包括
好处、类别、原则、最佳实践、术语表和参考文献。 -
顺序
从基础概念和类别开始，接着是原则或实践，最后以术语表和参考文献结束。
3.5. 分类法和定义
概念性过渡使用散文，可扫描的技术内容使用术语-定义列表。
-
章节引导
用一个或两个段落开始一个主要章节，解释该章节的分类维度或目的。
-
术语-定义模式
将技术标签呈现为项目符号，并将其解释呈现为缩进的块引用。
- 原子性 > 原子性确保事务作为一个整体完成，或者在未保留部分结果的情况下回滚。 -
分组模式
当子章节包含多个不同的视角（例如约定、示例或工具）时，使用有序列表项作为本地组标题。
-
标签大小写
概念性标签使用标题大小写，描述使用句子大小写。
-
描述质量
以术语的角色、行为或定义属性开始描述。避免重复标签而不增加含义的循环定义。
3.6. 示例和数据
-
独立示例
使用
示例：引入散文级别的独立示例。在分组子章节（如示例和解释）中，改用描述性示例标签。 -
代码示例
使用带有最准确语言标识符的围栏代码块。
-
内联语法
对命令、文件路径、配置键、标识符、字面量和短语法片段使用反引号。
-
表格
使用 Markdown 表格进行紧凑的比较、矩阵、指标、命令或枚举参考数据。保持单元格内容平行，避免在单元格内使用散文段落。
-
图表
当关系或流程无法通过散文或表格有效解释时，使用基于文本的图表，例如 Mermaid。
-
标注
谨慎使用 GitHub 标注，用于约束、警告、交叉链接或会实质改变解释的信息。
> [!NOTE] > 该指标阈值取决于引用的报告周期，必须在发布前进行验证。
3.7. 参考文献
每篇文章以一个编号的 参考文献 章节结束。
-
内部参考文献
使用仓库相对链接引用相关的 Sentenz 文章。
- Sentenz [版本控制](../articles/versioning.md) 文章。 -
外部参考文献
在链接标题前注明组织或发布者名称，并在链接后标识来源类型。
- NIST [安全软件开发框架 (SSDF) 版本 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) 出版物。 - Kubernetes [文档](https://kubernetes.io/docs/) 文档。 - GitHub [DORA 四项关键指标](https://github.com/dora-team/fourkeys) 仓库。 -
来源类型
使用精确的限定词，例如
文章、文档、页面、出版物、仓库、报告、规范或标准。 -
相关性
仅包含在文章中引用或实质性使用的来源。不要创建与文章主张无关的通用阅读列表。
4. 工作流程
4.1. 创建
-
检查
阅读目标文章目录中的相邻文件。记录本地的标题词汇、链接样式、代码围栏约定以及相关的内部文章。
-
范围
定义文章主题、预期深度和主要分类维度。将相邻主题分隔成交叉链接的文章。
-
研究
收集权威的原始来源。验证术语、标准、指标、产品行为和时间敏感细节。
-
大纲
选择所需的规范章节，并在起草散文之前构建一个编号的标题层级。
-
加载模板
创建新文章时加载
assets/technical-article-template.md。移除对主题无贡献的章节。 -
起草引言
编写 H1 标题和一两个定义性段落。建立主题和工程背景，避免过早引入实现细节。
-
构建目录
镜像计划中的标题层级，并生成精确的 GitHub 兼容锚点。
-
编写章节
仅在有助于理解的地方添加章节引导、术语-定义列表、示例、表格、图表和标注。
-
添加参考文献
添加内部相对链接和外部来源限定的参考文献。确保每个重要的外部声明都有适当的权威来源。
-
验证
在返回或提交文章之前，应用所有质量门。
4.2. 修订
-
保留意图
在更改结构之前，识别现有文章的主题、范围和分类法。
-
加载模板
在修订文章之前加载
assets/technical-article-template.md。将其作为结构基线，移除不适用的模板章节，并保留有效的文章特定章节。 -
诊断
将缺陷分为技术准确性、分类法、组织、语言、格式、链接、示例和参考文献。
-
规范化
使标题、引言、目录、编号、标题级别、列表、块引用、代码围栏和参考文献与本文档保持一致。
-
精炼语言
用直接的技术定义和领域适当的动词替换模糊、重复、会话式或宣传性的措辞。
-
协调导航
在每次标题或文件名更改后更新锚点、交叉链接和参考文献。
-
验证
重新运行所有质量门，并确认修订在没有明确理由的情况下没有移除技术上相关的信息。
4.3. 审查
-
加载模板
在审查文章之前加载
assets/technical-article-template.md。将其作为结构基线，并且除非缺失的可选章节造成完整性和连贯性问题，否则不将其报告为缺陷。 -
评估
按以下顺序审查文章：
- 技术正确性
- 范围和分类连贯性
- 结构符合性
- 术语和缩略语
- 示例、表格和图表
- 链接和参考文献
- 语法、标点和可读性
-
报告发现
报告发现时，需注明受影响的标题或行、缺陷、其技术后果以及具体的修正建议。优先处理事实错误和结构不一致，而非风格偏好。
5. 风格指南
5.1. 语气和口吻
-
现在时
定义、能力和当前实践使用现在时。
-
过去时
仅对历史事件或已废止的行为使用过去时。
-
主动语态
当行动者或机制重要时，优先使用主动语态。
-
被动语态
当过程或结果是焦点且行动者无关紧要时，使用被动语态。
-
非人称视角
避免使用第一人称和第二人称代词。
-
专业化语气
语言应保持权威但严谨。使用技术术语，避免模糊的限定词（如“非常”、“大量”），并优先使用定量或可操作的语言。
5.2. 术语
-
一致性
在整篇文章中对同一概念使用相同的术语。不要为了多样化而交换同义词。
-
定义
首次在非平凡上下文中引入技术术语时进行定义。如果术语属于标准领域词汇，则不需要单独定义。
-
缩写
在首次使用时定义缩写，但引用的实体（如公司或产品名称）通常以标准形式呈现的除外。
-
避免行话
避免不必要的行话、过时的隐喻和营销用语。如果一个术语被广泛使用但定义不明确，请加以澄清或寻找替代术语。
5.3. 句子和段落
-
句子长度
保持句子简洁。拆分包含多个从句的长句。
-
段落结构
每个段落处理一个主题。第一句介绍段落主题。
-
过渡
在章节之间使用明确的过渡。不要依赖编号作为唯一的排序机制。
-
强调
使用有序结构（如列表或定义）进行强调，而非使用粗体、斜体或感叹号。
5.4. 列表和引用
-
无序列表
使用
-作为项目符号。 -
有序列表
用于序列或优先级顺序。
-
块引用
使用
>表示引用或术语定义。不要在块引用中嵌套其他块引用，除非是标准引用格式。 -
列表内的段落
在列表项中使用缩进的块引用或子列表来处理多句解释。
5.5. 链接和引用
-
链接文本
在括号中使用描述性文本。不要使用“此处”、“此链接”或裸 URL。
-
引用格式
在文本中使用数字引用（例如
[1]）。在文章末尾的参考文献章节中提供完整的引用详细信息。 -
文献引用
使用基于作者的引用于学术或正式参考文献。使用基于数字的引用用于标准或文档链接。
5.6. 代码、表格和标注
-
内联代码
对命令、文件路径、配置键、标识符、字面量和短语法片段使用反引号。
-
代码块
使用带有语言标识符的围栏代码块。在块内不要使用行持续符。
-
表格
使用 Markdown 表格。对齐列。不要使用 HTML 表格。短表格优先于长列表。
-
标注
遵循 GitHub 标注语法。使用
[!NOTE]、[!WARNING]和[!IMPORTANT]类型。
6. 质量门
应用以下检查以确保最终文章的一致性和可靠性。
-
技术正确性
- 所有可验证的主张是否都有 参考文献 支持？
- 时间敏感的信息是否已标记为过时或已更新？
- 代码示例能否成功编译或执行？
-
结构符合性
- H1 标题是否包含正确的主题名称？
- 引言是否在第一个 H2 之前？
- 目录 是否完整且锚点是否有效？
- 所有章节是否都正确编号？
- 模板中不适用的章节是否已移除？
-
语言
- 语气是否正式、百科全书式且非人称？
- 是否避免了会话式表达、修辞问题和宣传性措辞？
- 除非必要，是否避免了第一人称和第二人称？
-
格式
- 代码块是否有语言标识符？
- 表格是否格式正确？
- 标注是否使用正确的语法？
-
导航
- 所有内部交叉链接是否有效？
- 所有引用链接是否有效？
- 目录是否与标题匹配？
-
内容
- 示例是否清晰相关？
- 术语是否定义一致？
- 分类法是否连贯？
7. 资源
8. 参考文献
- Sentenz README 文章。