ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

TigerBeetle 技术文档写作规范(Docs Style Guide)全解析:从文档分层到微观写作守则

TigerBeetle 技术文档写作规范(Docs Style Guide)全解析:从文档分层到微观写作守则 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而非主站点 仓库副本的主次关系官方文档站点渲染由 TigerBeetle 自研的静态站点生成器渲染即 docs.tigerbeetle.comGitHub 内建 Markdown 渲染在仓库中直接用 GitHub 的 Markdown 渲染器阅读本地文本编辑器中的原始 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 校验的一整套闭环而不只是写作时的自觉。三、宏观分层MacroDjango 式用户文档 TigerBeetle 特色概念文档 随性的内部文档指南的 Macro 部分回答的问题是文档应该分成几类、每类承担什么职责、分别给谁看。它借鉴了 Django 文档的组织方式并为用户文档定义了三种形态再加上 TigerBeetle 自己添加的第四种概念文档以及独立的内部文档体系。3.1 用户文档三分法Tutorial / Guides / Reference用户文档大体遵循 Django 风格组织共分三种形态形态目标读者写作目标仓库实例Tutorial教程初学者、尚未使用产品的用户端到端快速走查带着读者做具体的事、达成具体目标不必要解释每个细节原理docs/start.md从下载二进制、format、start、repl到创建账户、发起转账的完整上手流程Guides指南已掌握基础、想把某件事做成的新用户对某一领域的深度讲解必须始终解释为什么Whydocs/coding/ 与 docs/operating/ 下的所有页面如 docs/coding/two-phase-transfers.md、docs/operating/deploying/docker.mdReference参考需要精确行为定义的开发者以最高精度规定行为不是从头到尾读完的文档而是随机访问random-access的文档docs/reference/如 docs/reference/transfer.md、docs/reference/create_transfers.md三者的边界在于目的Tutorial 重在带人做完Guides 重在讲清为什么Reference 重在精确到不容歧义。一个有趣的细节是Guide 与 Tutorial 的关键区别被明确写为unlike tutorials, guides shouldalwaysexplain the why——教程允许读者先跑起来再说指南则必须把每个决策背后的理由讲透。3.2 TigerBeetle 特色Concepts概念与原则在 Django 结构之上TigerBeetle 加了自己的twistConcepts 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.mdOLTP等它们回答的是为什么是双式记账为什么如此追求安全这类设计哲学问题。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。文档的价值不在于字数而在于覆盖的概念数字数是成本。由此推导出推荐的写作流程列出所有想传达的事实list all the facts that you want to communicate找到能清晰、简洁地解释全部所列观点的最短词集find the shortest set of words that explainalllisted ideas。少而准而非多而全是这条守则的灵魂。其余微观守则可归纳为以下几组4.1 链接与结构Cool URIs dont changeCool URIs dont 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 lines100 列硬上限硬换行宽度为 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 文档作者的实际工作流可以归纳为先判断文档类型内容是要带新手跑通Tutorial、讲透某个领域的为什么Guide、精确定义 API 行为Reference还是阐释设计理念Concepts不确定归属、且属于内部知识就先丢进 docs/internals/ 目录后续再整理按类型决定写法Guide 必须回答 WhyReference 追求最大精度、可随机访问Tutorial 允许暂不解释原理先列事实再压缩词数遵循 Dijkstra 的行为成本观列出全部要点后用最短词集覆盖宁少勿滥守住微观红线GFM、100 列硬换行、Oxford comma、美式英语、_/**强调、-列表一条都不能破谨慎命名文件名与章节名即 URL发布前想清楚Cool URIs dont change让工具把关链接与页面完整性由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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表