AI 赋能技术文档全流程写作

文档本质上是一种用户体验（UX），而不是事实摘要。至少，我是这么看的。

作为开发者，我们天生就想要证据，因为我们骨子里并不轻信。我们不只希望某个东西“能用”，还希望确认自己对输入、输出，以及让它真正运行起来的具体过程都心中有数。

所以，当用户打开我们的文档时，那就是我们的机会。我们不仅要证明这个工具是真实可用的，还要证明工具背后的人确实在乎用户能否成功——而这一点，应该直接体现在文档本身。

在我看来，文档是最直观的产品质量指标之一。

作为用户，如果我们读到的文档已经过时，与应用中的实际体验或服务的实际使用方式对不上，心里难免会留下不好的印象。

更具体地说，文档会向用户透露：产品的架构质量如何、变化频率有多高，以及工程团队与体验团队之间的内部协作是否一致。

它会告诉用户，这个产品究竟是真的靠谱，还是它唯一的目标只是做出一个看起来靠谱的东西。

每当我在 Pieces 编写一篇新指南，或者重新组织一部分文档时，我都会想到这一点。文档本身与产品一样，也是一种产品。它负责销售、传递信息、提供示例、带来洞察，因此非常重要。

文档就是基础设施

别再假装文档只是“辅助内容”，或者只是一本嵌入了几段精美媒体素材的高级用户手册了。

不是这样的。文档就是基础设施。

它是用户驾驭复杂性的接口，是连接用户意图与系统行为的桥梁。当产品中有什么地方不对劲时，用户会阅读文档来理解它——如果文档与产品的真实情况或实际能力对不上，就会发出一个明确的信号：这里还需要投入更多工作和用心。

这个流程大致如下：

从这个角度看，产品与支撑它的文档之间是一种高度共生的关系。

在 Pieces，我会尽量像工程师和开发者对待系统模块那样对待面向用户的文档——采用一种“Docs as Code”的方式：

它有自己的影响面。

因此，无论我是在编写 LLM 部署指南，还是 MCP 设置流程，我首先思考的问题都不是：

“我要怎么解释这件事？”

“应该用哪些准确的措辞？”

好吧，说实话，有时候我确实得问这些问题。

但认真来说，我真正需要考虑的是：

“这部分内容如何融入产品的心智模型？”

“用户此刻想解决什么问题？”

“工程团队做出了哪些决定，而用户现在需要理解这些决定？”

“从这个功能到下一个功能的流程是否足够直观？”

把文档视为基础设施，意味着我们要像对待代码那样对待它：模块化、可维护，并且能够感知整个系统。我会用下面这种方式把它可视化：

Docs-as-Code 不是一种工作流，而是一种思维方式

人们很容易把 Docs as Code 说成一段 CI 脚本加上一些 markdown，但它远不止这些！

它意味着文档与代码库位于同一个 repo 中，或者至少遵循相同的节奏。

文档与功能一样，需要被编写、评审、合并、版本管理和部署。它需要在正确的时间点完成。

这还意味着：为了制作新图片、澄清信息，需要与增长团队成员协作；为了确认具体技术细节，需要与开发者开会；还要从用户视角进行一对一测试，以及大量独立测试，反复打磨 microcopy。

在 Pieces，这意味着：

• 每一个新功能都必须配套文档

• 新文档不仅由作者评审，还需要产品和工程团队共同评审

• 全新文档在合并之前需要经过暂存、测试和预览

• 文档更新通常与功能发布受同一个 flag 控制

为什么这很重要？

因为这样可以确保面向用户的文档不会落后于产品变化。

不会出现功能发布六周后才跟进“最终版指南”的情况，因为在理想状态下，文档应该与功能同步发布。这样一来，就不必猜测哪些内容已经上线、哪些内容还在开发中。

如果你无法解释一个功能，就不能发布它！

我具体如何编写文档，以及在哪里使用 AI

先说清楚：至少在现阶段，使用基础 AI 工具直接生成技术文档并不现实。

你需要花费太多精力来核查它的输出，确认它没有产生离谱的幻觉，让它真正生成可以复制的 markdown——这又是另一天的话题了……除此之外，还有更多问题。

生成 AI 文档需要处理大量复杂性并具备足够的上下文知识，从时间效率来看，这确确实实还不如我自己动手写。

不过，我会在写作过程中的几个“检查点”使用 AI。具体流程如下：

我会对着转录工具把问题讲一遍。不追求措辞完美，只需要说出想法、角度、结构，也许再加上一些类比，或者讲讲“用户在这里需要理解什么”。

有时候，我会描述某个真实的 UI 元素，甚至整个视图；也会讲述自己如何从一个按钮操作到另一个按钮，以及在我完全掌握使用方法之前，各处 microcopy 对我意味着什么。这些上下文至关重要。

使用 LLM 拆解

我会把转录内容粘贴到一个全新的对话中，让它整理出 markdown 风格的结构。

我会通过 prompt 让它给出一个带标题层级的页面大纲：只需要最基础的结构，暂时不用考虑具体的 markdown 实现，例如 components、frontmatter 等。

现在，我就有了一个层级清晰的初始结构，可以在此基础上继续打磨，而且其中已经融入了我真实的实践经验和体验上下文。

接下来，我会逐行处理，真正动手编写每一个章节。

我会把项目符号中的概念扩展成完整的句子，并在写作时采用“蛙跳式”的方式——也就是说，每开始一个新章节，我会先保留那个项目符号，等段落写完后再回来处理它。

有时候，我会停下来检查：

“这个解释是否由前面的前提自然推导而来？”

我会把 H2 标题和对应段落粘贴进去，让 LLM 从逻辑或清晰度的角度进行审查，而不是检查语气——这也是 prompt 评估的一部分。

我们都知道，AI 在真正理解自然的人类语气方面表现得很糟糕——所以不要尝试用 LLM 来改善文章的“声音”“感觉”或“味道”。

提示：我在编写 prompt 时使用的关键词之一是“chronological”，尤其是在判断一篇文档的流程和连贯性时。我会使用“chronological”来引导 LLM 检查标题结构，以及那些粗略写成、但完全由人工编写的段落和章节能否自然衔接，从而确保没有内容出现在不合适的位置。

最后，我会把完整文章连同最初的转录内容一起粘贴进去——这可能是整个过程中最重要的一步。

它会告诉我：最终成品是否真正遵循了最初的思路；是否回答了我作为用户时提出的问题；是否实现了目标；逻辑是否成立；以及它能否融入更大的整体背景——前提是我提供了额外的上下文。

然后……我会收到一堆问题标记，因为人都会犯错，而我也是人。于是，我会修正所有被标出的拼写错误、逻辑错误和其他问题。只有到这时，我才会称它为一份“草稿”！

LLM 不会替我写作。它们会挑战我的结构、发现我的盲点，并在我陷入过多细节或过度解释时及时提醒我。

这才是它们真正有用的地方。

对我来说，写作有几种不同的风格，或者说不同的“状态”。

平静写作、迭代起草，以及彻头彻尾的混乱。

平静写作：看来我需要更新这一节的安装说明。我得确认另一个地方也同步更新了。

迭代起草：好吧，这一部分相当复杂。不过既然这三个页面已经整理到一起了，我得确认它们都遵循相同的结构约定。看来我忘了在这里使用 callout，我来补上。

彻底混乱：我需要重写整个 Pieces Desktop app 的文档。现在有三个新功能、两处发生变化的引用，需要在八套彼此独立的文档中进行调整，而我甚至还没开始考虑媒体素材……

当我进入第三种状态时，我会使用 Pieces 帮助自己处理待办事项、会议记录和通用上下文。

不是用它来写作，而是用它来记忆——长期记忆正是我们产品的一切。

当我们迁移整套文档技术栈时，我手头有：

• 四次对话的笔记

• 来自 Figma 重新设计的视觉参考

我不打算手动整理这些内容。我没有足够的脑力一边在混乱模式下写作、一边搭建新平台，同时还要记住每一位工程师提出的每一条笔记、请求或需求。

所以，我会定期、持续地把能保存的内容都存进 Pieces，这样我就不需要自己记住它们了！

这为我需要编写和串联的一切提供了本地、实时且带有上下文的线索。我不必来回翻阅聊天记录，不必同时打开五份 Google docs，也不必重读上周某次会议的转录内容——那份记录可能早已埋在我的电子邮件里。

Pieces 就像我的记忆层。我可以持续专注于文档写作，需要时再查阅我的 Long-Term Memories。

Pieces 不仅会保留我主动存储的内容，还会持续捕获新的工作流记忆，因此它能够“自我更新”，并在我需要时立即提供最相关的内容——这正是它擅长的事情。

如果我需要在不同工具之间切换、重新找回上周开发会议中的某项决策，或者回忆某个 config flag 在 beta 版本中是如何表述的——这时 Pieces 就会重新进入工作流。

对于开发者来说，它非常适合捕获中间过程中的工作内容，例如正在测试的代码、希望保留的结果，以及不想遗忘的日志。

把文档当作产品来构建

文档中的每一个标题，都像 UI 中的一个 modal。每一个段落，都是帮助用户理解内容的 function signature。

每一个列表都是一道抽象边界；每一段文案都和应用中最关键的 microcopy 一样重要。文档反映的是那个藏在炫目营销网站背后的真实产品——诸如此类……

……但如果文档坏了，用户就会离开；如果文档做得好，他们就会信任你。

正因如此，我和 Pieces 的文档团队是在“设计”文档。这显然不同于仅仅发布 release notes 或更新 changelog——顺便说一句，我们也有自己的 changelog，值得持续关注。

这种差异会体现在这样的时刻：用户来到我们的文档网站，阅读设置指南或 Get Started 章节，运行安装脚本，然后说：“嘿，它居然真的成功了。而且这份文档看起来也很舒服。让我再四处点点看……”

产品的信任正是在这里建立起来的，而这就是我想要构建的东西。