当写书像写代码:用Git、Markdown和CI构建一本「过度工程」的书

挖矿与质押

在数字化时代,写作不再仅仅是作家或记者的专利。越来越多的技术从业者开始用代码思维来重新定义写作流程。本文主人公本·鲍尔特(Ben Balter)就是这样一位跨界实践者 - - 他将软件工程的方法论应用于写作,用Git管理文本、Markdown编写内容、CI/CD流水线构建发布,最终打造了一本「过度工程」的书《Open & Async》。这本书不仅内容本身获得好评,其背后的工具链和自动化流程也成为了技术写作的典范案例。**从Word文档到Git仓库:写作工具的革命**大多数人写书的第一步是打开Word或Google Docs,但本·鲍尔特选择了完全不同的路径。作为一名有十多年网站开发经验的工程师,他习惯性地将写作视为一个代码项目。

于是,他决定用Git来管理书籍的内容,用Markdown编写每一章节,用持续集成(CI)来自动构建和验证书籍的各种格式。这种看似「过度工程」的做法,实际上源于他对工具效率的深刻理解。在传统出版流程中,作者通常需要在Word中完成初稿,然后交给编辑、设计师和排版师处理。而本选择从一开始就将写作本身「工程化」:每一次修改都有版本控制,每一处语法错误都能实时被检测到,每一种输出格式都能自动生成。这种方法不仅提高了写作效率,还确保了内容质量的可追溯性和一致性。**实时语法检查:让AI成为你的编辑助手**在写作过程中,本使用了多达六种实时语法检查工具,包括Markdownlint、Harper、LanguageTool、Vale、Alex和Write-good。

这些工具不仅能检测语法错误,还能识别语言风格问题,比如被动语态、陈词滥调、排斥性用语等。更有趣的是,他还为书中的特定内容定制了专门的检查规则。例如,由于他已经离开了GitHub,任何仍然使用现在时态描述他在GitHub工作的句子都会被自动标记为错误。他甚至写了一个Node.js脚本来检查这种错误,确保书中所有关于过去工作经历的描述都使用过去时态。这种「一次犯错,终身受益」的理念,正是软件工程中「将错误转化为规则」的最佳实践。**自动化测试:让质量检查像代码测试一样严格**如果说实时检查是写作过程中的「预防针」,那么自动化测试就是「疫苗」。

本为这本书构建了一个庞大的测试套件,包含约70个测试文件、2204个测试用例和近5500个自动化检查。这些测试不仅检查语法和拼写,还涵盖了内容结构、交叉引用、术语一致性等多个维度。其中最有趣的是「重复内容检测」功能。为了避免书中出现相同观点的重复表述,他构建了三层检测机制:第一层是基于代码复制检测工具jscpd的逐字重复检查;第二层是基于n-gram算法的短语重复检测;第三层则是使用大语言模型进行语义重复检测。这种多层次的检查确保了书籍内容的原创性和逻辑严密性。**多格式自动发布:一本书,五种形态**传统出版流程中,一本书通常只以纸质或电子书形式发布。

但本选择了更复杂的路径:他用同一份Markdown源代码,通过Pandoc转换引擎生成了EPUB、Kindle专用EPUB、纸质PDF、PDF/X-1a(适合印刷)和网页版HTML五种格式。为了实现这一点,他构建了一个完整的发布流水线。首先,源代码经过预处理脚本进行格式转换,比如将内联链接转换为脚注以适应纸质版本。然后,通过Tailwind CSS进行样式设计,确保不同格式的视觉一致性。接着,使用Lua脚本对Pandoc的抽象语法树进行微调,添加特定格式的元素(如为EPUB添加分享链接,为纸质版添加页码)。最复杂的部分在于表情符号的处理。

由于不同设备对透明度的支持程度不同,他不得不为Kindle和纸质版分别定制解决方案。最终,他通过Python脚本在构建时生成两种不同的表情符号格式,确保在所有设备上都能正确显示。**持续集成:让每一次提交都经过严格验证**为了确保每一次代码提交都不会引入错误,本构建了一个14个并行任务的CI流水线。每次推送到主分支时,系统会自动执行以下操作:1. 构建CSS样式表2. 生成EPUB、Kindle EPUB、纸质PDF、PDF/X-1a和HTML版本3. 运行可访问性测试(使用axe-core检查WCAG 2.1 AA合规性)4. 执行视觉回归测试(使用Playwright检查布局一致性)5. 通过EPUBCheck和Ace by DAISY验证EPUB格式6. 检查链接完整性(使用lychee检测失效链接)7. 验证HTML语法整个流程在大约5分钟内完成,确保任何错误都能在第一时间被发现。这种「主分支始终可发布」的理念,正是现代软件开发的核心原则。**为什么要「过度工程」一本书?**面对这种「过度工程」的做法,许多人可能会质疑其必要性。

但本的回答很简单:「这不是拖延症,这是真正的严谨」。在他看来,每一个自动化检查都有其存在的价值,因为它们捕捉到了人眼无法发现的错误。更有趣的是,这种工具链的思维方式不仅应用于写书,还扩展到了他的其他项目。他甚至将同样的方法应用于自己的博客文章,发现了2011年一篇文章中长期存在的拼写错误。这种「主动寻找问题」的习惯,正是优秀工程师和普通从业者的区别所在。**技术写作的未来:内容即代码**本的实践证明了一个道理:写作和编程并非截然不同的活动。

通过将内容视为代码,我们可以利用软件工程的最佳实践来提高写作效率和质量。这种「内容即代码」的理念正在被越来越多的作家、记者和内容创作者所采纳。对于技术写作者而言,这种方法尤其有价值。通过自动化流程,他们可以专注于内容创作本身,而将格式转换、语法检查、版本控制等繁琐工作交给机器完成。这不仅节省了时间,还提高了作品的专业性和一致性。**给写作者的启示**本的经验告诉我们,工具的选择决定了工作的效率。

如果你习惯于使用Word或Google Docs,那么写作过程可能充满了手动操作和重复劳动。但如果你像开发软件一样对待写作,那么你将获得前所未有的控制力和效率。当然,并非所有写作项目都需要如此复杂的工具链。但了解这些可能性,至少能让你在选择工具时做出更明智的决策。无论你是写小说、技术文档还是商业报告,总有一种方法能让你的写作过程更加高效和可靠。**结语:写作的下一个边界**本·鲍尔特的实践展示了技术如何重塑传统行业。

在出版业普遍使用Word作为起点的时代,他选择从Git仓库开始。这种「反直觉」的做法,最终证明了其价值:不仅提高了写作效率,还确保了作品质量的可控性。对于未来的写作者来说,最大的启示或许不是具体的工具或流程,而是这种「系统性思维」。当我们开始用工程的方法来思考写作时,我们不仅在创造内容,更在构建一个可持续发展的知识生产系统。这种思维方式,或许正是写作行业下一个十年的发展方向。 。