企业官网建设流程全解析

TigerBeetle 技术文档写作规范（Docs Style Guide）全解析：从文档分层到微观写作守则

【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle

本文以 TigerBeetle 仓库中的内部文档 docs/internals/docs.md（即仓库自身的技术文档写作风格指南，Docs Style Guide）为骨架，结合仓库内文档目录结构与src/docs_website静态站点生成器源码，完整讲解 TigerBeetle 如何组织、编写与校验技术文档。读者读完本文，可以掌握这套"宏观分层 + 微观守则"的文档方法论，理解为何文档要与代码一同被严肃对待，并能直接参照其规范为 TigerBeetle 或自有项目编写高质量技术文档。

一、文档是 TigerBeetle 数据库的一部分

这份写作风格指南开宗明义：用户文档与开发者文档都被视为 TigerBeetle 数据库不可分割的组成部分（"Both user and developer docs are considered to be integral parts of TigerBeetle database"）。这与大多数开源项目"文档只是附属品"的定位截然不同——在 TigerBeetle 中，文档不是事后补充的说明材料，而是与数据库本体同等重要的交付物。

这一判断并非空话，仓库中的佐证随处可见：

• 仓库根目录下的 docs/README.md 明确说明整个文档体系服务于"financial transactions database"这一核心，并按 Start、Concepts、Coding、Operating、Reference 五大板块组织；
• 代码风格总纲 docs/TIGER_STYLE.md 明确声明"TIGER_STYLE applies to documentation as well!"，即文档同样受 TIGER_STYLE 约束；
• 文档甚至有自己的专用构建与校验工具链（见下文第四节），CI 中会专门检查文档链接与拼写。

因此，TigerBeetle 的文档写作不是"会写字就行"，而是一套有明确规范、有工具支撑、有 CI 保障的工程实践。

二、三种一等呈现方式：一份 Markdown，三种打开方式

该指南指出：文档独立于呈现方式而存在（"Documentation exists independent of presentation"），以下三种呈现形式都被视为一等公民（first-class），而非"主站点 + 仓库副本"的主次关系：

1. 官方文档站点渲染：由 TigerBeetle 自研的静态站点生成器渲染，即 docs.tigerbeetle.com；
2. GitHub 内建 Markdown 渲染：在仓库中直接用 GitHub 的 Markdown 渲染器阅读；
3. 本地文本编辑器中的原始 Markdown：直接以源码形式查看。

三种呈现方式平等的直接后果是：文档内容必须用纯 Markdown 写成，不得依赖某个站点特有的语法或插件。这一点在第 53 行被明确为规则："Because docs are viewable on GitHub, GitHub Flavored Markdown is used for all the content"（所有内容使用 GFM，即 GitHub Flavored Markdown）。

仓库中src/docs_website目录正是"第一种呈现方式"的实现。从 src/docs_website/README.md 可以看到整个构建流程：

• 输入：/docs目录下的 Markdown 文件，以及/src/clients/$lang/README.md（各语言客户端的 README 也会被纳入站点文档）；
• 链接检查：由./src/file_checker.zig负责；
• 拼写检查：由 vale 执行，接受词表维护在./styles/config/vocabularies/docs/accept.txt；
• 输出：静态 HTML 文件写入./zig-out目录；
• 触发方式：ci.zig在合并队列中触发（主要用于检测失效链接），release.zig在发版时触发并推送渲染后的文档。

也就是说，这份写作规范中"三种呈现方式平等"的原则，最终落实成了"GFM 语法 + 构建器解析 + CI 校验"的一整套闭环，而不只是写作时的自觉。

三、宏观分层（Macro）：Django 式用户文档 + TigerBeetle 特色概念文档 + 随性的内部文档

指南的 Macro 部分回答的问题是："文档应该分成几类、每类承担什么职责、分别给谁看"。它借鉴了 Django 文档的组织方式，并为用户文档定义了三种形态，再加上 TigerBeetle 自己添加的第四种"概念"文档，以及独立的内部文档体系。

3.1 用户文档三分法：Tutorial / Guides / Reference

用户文档大体遵循 Django 风格组织，共分三种形态：

三者的边界在于目的：Tutorial 重在"带人做完"，Guides 重在"讲清为什么"，Reference 重在"精确到不容歧义"。一个有趣的细节是：Guide 与 Tutorial 的关键区别被明确写为"unlike tutorials, guides shouldalwaysexplain the why"——教程允许读者先跑起来再说，指南则必须把每个决策背后的理由讲透。

3.2 TigerBeetle 特色：Concepts（概念与原则）

在 Django 结构之上，TigerBeetle 加了自己的"twist"：

Concepts and principles explain why TigerBeetle is the way it is. From principles, the rest follows. Tutorials, Guides, and the Reference are documents about TigerBeetle as implemented, while the concepts speak to the Platonic ideal of the beetle.

即：Concepts 解释"TigerBeetle 为什么是这样"，其余三类文档描述"TigerBeetle 实际上是什么"。前者谈论的是"甲虫的柏拉图式理想形态"（the Platonic ideal of the beetle），后者记录的是已实现的现实。仓库中 docs/concepts/ 下正是这类文档，例如 docs/concepts/debit-credit.md（借贷记账原理）、docs/concepts/safety.md（安全性设计）、docs/concepts/oltp.md（OLTP）等，它们回答的是"为什么是双式记账""为什么如此追求安全"这类设计哲学问题。

3.3 内部文档（Internals）：刻意"反结构化"的组织方式

与用户文档严格的分层不同，内部文档不遵循任何特定结构（"internal docs do not follow any specific structure"）。指南用了一个很特别的词来形容内部文档的定位："ingest optimized"（为摄取/消化优化）——核心诉求是"先有东西被记录下来"，而不是"记录风格统一"。

相应的组织策略是：

If you are unsure where something needs to be documented, just add a new file into the./internalsfolder: it will get properly reorganized & compacted with time!

即"不确定该放哪，就新建一个文件丢进 internals 目录，时间会负责整理与压缩"。这种务实策略承认了内部知识天然混乱的事实，先用极低的写入成本保证知识不被遗漏，再靠后续维护收敛结构。仓库 docs/internals/ 目录正是这一哲学的产物：既有面向新读者的 ARCHITECTURE.md（一页纸技术入门）、HACKING.md（构建与测试上手）、data_file.md（数据文件布局），也有深入共识协议与存储引擎的 vsr.md、sync.md、lsm.md，以及本指南所在的 docs.md 本身。

从 docs/internals/README.md 可以清楚看到，内部文档被精心组织为一条由浅入深的阅读路径：TIGER_STYLE（哲学）→ ARCHITECTURE（入门）→ HACKING（上手）→ Data File（第二读）→ VSR（共识上半层）→ LSM（存储下半层）→ 再延伸到测试与发布。这说明"不设强制结构"并不等于"没有组织"，而是把结构的选择权交给了内容本身。

3.4 目录结构如何被构建器"固化"

文档分层不只是写作层面的约定，src/docs_website的构建器源码把它固化成了可执行的逻辑：

• src/docs_website/src/content.zig 从/docs目录递归构建目录树（ToC），其Page结构体包含content、path、children，目录节点的子页面通过解析 README 中的链接获得；
• 每个.md文件的首行必须以#开头作为标题（parse_page_content中cut_prefix(title_line, "# ") orelse return error.TitleInvalid），否则构建报错；
• ToC 链接必须是- [列表形式，且路径必须以./开头、以/或.md结尾（parse_page_child中的硬校验），这实际上把"README 里怎么写导航链接"变成了机器强制规则；
• 构建器还会检查目录下每个文件是否都被 README 链接覆盖，未被引用的页面会报orphaned page错误——与指南"文档是数据库的一部分"一脉相承，孤儿页面会被直接拒绝。

客户端文档则被特殊对待：src/docs_website/src/docs.zig 的page_url中把/src/clients/$lang下的 README 映射到站点 URLcoding/clients/$lang，与用户文档中 docs/coding/clients/ 的读者路径保持一致。

四、微观守则（Micro）：一行文档，一行成本

Micro 部分是这份指南的"写作纪律"部分，回答"具体到每一个句子怎么写"。它最核心的理念来自 Dijkstra 的一句转述：

我们应当把每一行文档看作一笔花费（a line spent），而非一行产出（a line produced）。文档的价值不在于字数，而在于覆盖的概念数；字数是成本。

由此推导出推荐的写作流程：

1. 列出所有想传达的事实（list all the facts that you want to communicate）；
2. 找到能清晰、简洁地解释全部所列观点的最短词集（find the shortest set of words that explainalllisted ideas）。

"少而准"而非"多而全"，是这条守则的灵魂。其余微观守则可归纳为以下几组：

4.1 链接与结构：Cool URIs don't change

Cool URIs don't change! Think hard about file and section names, as they form parts of URLs.

认真对待文件名与章节名，因为它们会成为 URL 的一部分，而"酷的 URI 不会变"。这意味着文档页面的标题、章节锚点一旦发布，就要尽量保持稳定，避免日后重构导致大量外部链接失效。这与第四节的构建器逻辑互相印证：页面标题直接来自 Markdown 首行#（content.zig 的解析规则），改名即改 URL。

4.2 排版与语言规范（可操作清单）

指南给出的具体排版守则如下，全部服务于"一份 Markdown 三种呈现方式"的一致性目标：

• GFM 语法：因为文档要在 GitHub 上渲染，全部内容使用 GitHub Flavored Markdown；
• 长行硬换行：保持源码可读性，硬换行包裹长行（hard wrap long lines）；
• 100 列硬上限：硬换行宽度为 100，因为这是 TIGER_STYLE 的规定（TIGER_STYLE 中同样有"所有行长度硬限制 100 列"的规则，动机是恰好能在屏幕上并排放下两份代码/文本）；
• Oxford comma：枚举使用牛津逗号（A, B, and C）以保持一致性；
• 标准美式英语：统一使用 Standard American English；
• 强调语法统一：弱强调（斜体）用_underscores_，强强调（粗体）用**double stars**；
• 列表符号统一：列表用-而非*。

这些规则琐碎但可验证——它们确保了同一份 Markdown 在任何渲染器、任何编辑器中看起来、读起来都是一致的。

4.3 规则与仓库实现的双向印证

微观守则并不只是纸面建议。仓库的构建与校验工具链实际上承担了"规则执行者"的角色：

• 链接校验：src/docs_website/src/file_checker.zig 会遍历生成目录，对每个文件按扩展名分类（文本类.css/.html/.js/.json/.svg/.xml，二进制类.avif/.gif/.jpg/.png/.ttf/.webp/.woff2，以及CNAME、.nojekyll等例外），任何超出预期的文件类型都会导致校验失败，同时检查产物文件体积上限（如单页最大 2 MB）；
• 拼写与词汇表：vale 负责拼写检查，接受词表维护在 src/docs_website/styles/config/vocabularies/docs/accept.txt——这正是"Standard American English 一致性"的机器化手段；
• 导航与单页：src/docs_website/src/docs.zig 还会为每页生成导航 HTML、统一的 single-page-link、以及全站search-index.json搜索索引，并支持将全部文档渲染为单页版本，进一步印证了"文档独立于呈现方式"的设计——同一批 Markdown，同时产出多页站点、单页版本与搜索索引。

五、这套规范对文档作者意味着什么：一份可执行的写作流程

综合 Macro 与 Micro 两部分，一名 TigerBeetle 文档作者的实际工作流可以归纳为：

1. 先判断文档类型：内容是要"带新手跑通"（Tutorial）、"讲透某个领域的为什么"（Guide）、"精确定义 API 行为"（Reference），还是"阐释设计理念"（Concepts）？不确定归属、且属于内部知识，就先丢进 docs/internals/ 目录，后续再整理；
2. 按类型决定写法：Guide 必须回答 Why，Reference 追求最大精度、可随机访问，Tutorial 允许暂不解释原理；
3. 先列事实，再压缩词数：遵循 Dijkstra 的"行为成本"观，列出全部要点后用最短词集覆盖，宁少勿滥；
4. 守住微观红线：GFM、100 列硬换行、Oxford comma、美式英语、_/**强调、-列表，一条都不能破；
5. 谨慎命名：文件名与章节名即 URL，发布前想清楚（Cool URIs don't change）；
6. 让工具把关：链接与页面完整性由src/docs_website构建器与 file_checker 在 CI 中强制校验，拼写由 vale 检查，作者无需手工逐条核对。

这套规范与 docs/TIGER_STYLE.md 一脉相承：后者强调代码风格的三大设计目标是"安全、性能、开发者体验"，而文档风格指南则把同样的严肃性带到了文档领域——文档不是代码的附属品，而是数据库的一部分，值得与代码同等的纪律和工具支撑。对希望深度参与 TigerBeetle 的开发者而言，从 docs/internals/docs.md 出发，再对照 docs/README.md 的通读路径与 src/docs_website/README.md 的构建说明，即可完整掌握从"写什么"到"怎么写"再到"怎么被校验发布"的全链路。

【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle