我是如何过度设计我的书的

我的书里有一个检查器，因为我用连字符“开源”而对我大喊大叫。 1 它会运行约 5,500 次自动检查，在每次 git push 上重建五种格式，如果我暗示我仍在从事我离开的工作，则构建会失败。为了一本书。那个人写的。我并没有打算这样做。大多数人通过启动 Word 或 Google Docs 来开始写作项目，我也沿着同样的道路开始。我什至尝试了一些专门构建的创作工具，但每种工具都比我作为开发人员每天使用的工具要差。我做了“唯一合理”的事情，把它们全部扔掉，写了整本书关于 Git、Markdown 和 CI 构建管道。如果您已经读过我如何过度设计我的家庭网络（两次），那么这些都不会令您感到惊讶。我制作网站已经有几十年了，所以飞跃很短：构建网站的相同工具可以构建书籍，不需要最后一刻的魔术揭秘就能将标准 Word 文档变成一本成熟的书籍。虽然有一些失误，2 但最终，我不会以任何其他方式编写 Open 和 Async。方法如下： 内容 # 当然，内容本身以 Markdown 文件的形式存在于 Git 存储库中。毕竟，我一天大部分时间都在那里度过。我使用了 VS Code，以及一些散文扩展（如下所列）。每个章节都有自己的 Markdown 文件，并且单个 index.yml 文件定义了顺序，从而可以轻松地重新排序章节或添加新章节。实际上，我在 iPad 上写了这本书的大部分内容——浏览器选项卡中的 Codespaces、蓝牙键盘，通常是晚上和周末离开办公桌时写的——而且无论我在哪里打开它，Git 存储库都能使所有内容保持同步。我可以专注于文字，而一个坏主意就是从“消失”中恢复过来。更不用说，我在 IDE 中从各种散文 linter 中获得了关于我的写作的实时反馈，就像我从 ESLint 或 Prettier 中获得了关于我的代码的实时反馈一样。测试 # 将内容作为代码，下一个合乎逻辑的步骤——也是“合理”悄然离开建筑的点——是设置自动化测试。用测试代码的方式测试散文是我多年来一直争论的问题。这是我把它推向了荒谬的极端。我通过两种方式做到了这一点：实时和推送（CI）。实时 # 在本地，当我输入时，我运行了多个 VS Code 扩展，所有这些扩展都为我提供了实时反馈。具体来说： Markdownlint - Markdown 语法和格式一致性 Harper 3 - 语法和单词选择，完全在设备上 LanguageTool - 语法、标点符号和风格 4 Vale - 我自己的房屋风格规则和禁止术语 Alex - 不敏感或排他性的措辞 Write-good - 弱散文：被动语态、黄鼠狼的话、陈词滥调 所有六个也都在 CI 中运行（Alex 和 Write-good 并入 Vale；更多内容见下文）。他们一起在一个完整的语法引擎上分层了数百条精心设计的样式规则——所有这些规则都实时强调了我的错误，就像红色曲线标记类型错误一样。在每次推送时 # 除了在 CI 中运行这些开源 linter（有些阻塞）之外，我还构建了自己的自定义测试套件：内容验证器的独立 Node 脚本、Vitest 套件和 Playwright 规范。验证器是有趣的部分。每行都是读取 Markdown 并使用文件和行指针推送错误的几行。我最喜欢的：我不再在 GitHub 工作，所以任何声称我仍然在 GitHub 工作的句子都会导致构建失败。 // 我在 GitHub 的时间必须读作过去时 — 现在时 // 关于它的就业声明失败了。 function validateGitHubTense ( files ) { // "is/are ... at GitHub" — 当前就业声明 / \b (is | are) \b [ ^ .!?\n] {1,80}?\b at GitHub \b / i , // "works/leads/runs at GitHub" — 当前就业活动 / \b (works ?| Leads ?| running ?| Manages ?| directs ? ) \s + (at | for) \s + GitHub \b / i ，返回 flagLinesMatching (文件，模式);该验证器之所以存在，是因为我犯了一次错误——这就是整个模式。当我第一次遇到错误时，我不仅仅修复了那句话；我还修复了错误。我写了一条规则，这样我就再也不用亲眼看到它了。它是牛，而不是散文的宠物：不要手工护理每一章，用政策来管理整个牛群。一旦发现错误，就会成为检查每一章的检查，如果它再次出现，则构建会失败。这是大约三十个中的一个。其他让我感到自豪的： validateOpenSourceHyphenation —“开源”是一个名词，而不是动词，而且从不连字符。 validateHypotheticalHooks — 段落开头的公式化 AI 告诉开场白（“想象一下……”、“想象一下……”、“考虑一个……”）。 validateSentenceStarters — 以相同单词开头的连续三个以上句子。 validateNoBareUrlLinkText — 没有可见文本仅为原始 URL 的链接。 validateCalloutBalance — 本书面向经理和个人贡献者，因此“对于经理”标注必须在附近有一个“对于 IC”对应项。 validateCrossReferences — 每个 [text](#anchor) 交叉引用都会解析为真实标题。 …再加上几十个小型大写字母、破折号、双字、破折号范围、TL;DR 长度等等