最容易被低估的生产力武器：Figma 团队谈文档，句句戳中 AI 团队痛点

多数人把文档当成“项目结束后的负担”，但 Figma 在 Config 上抛出一个反直觉观点：文档不是结果，而是系统本身的一部分。这场关于 documentation 的分享，意外地为今天的 AI 团队、设计系统和协作方式，给出了一套极其可复用的方法论。

一个反直觉的开场：文档不是写给“以后”的

视频一开始，讲者就毫不掩饰自己对 documentation 的“偏爱”，但真正炸裂的点在于：他们讨论文档时，完全没有把它当成项目结束后的补充材料。在 Figma 团队的语境里，文档是活在系统里的，是和设计、组件、流程同时演进的东西。

这对很多 AI 从业者来说是个强烈对比。我们习惯把 README、Notion、Wiki 当成“交差物”，写完就不再动，结果就是：模型在变、流程在变，文档却在慢慢腐烂。Figma 提出的第一个关键认知是：文档之所以失败，往往不是因为写得不够好，而是放错了位置、出现得太晚。

从 Figma 文件内部开始：文档要离“变更源头”最近

在讨论不同层级的文档之前，视频先把镜头拉回一个极其具体的场景：Figma 文件内部的文档。为什么要从这里开始？因为这是设计系统最容易“出事”的地方。

他们强调，在设计文件内部清晰地标注文档信息，本质上是在做一件事：确保系统在被修改时“不会悄悄坏掉”。当组件被复用、被调整、被继承，如果缺少紧贴上下文的说明，后果往往不是立刻显现，而是在几周后以 Bug、返工、沟通成本的形式爆发。

类比到 AI 团队，这就像把关键假设、数据来源、模型限制写在代码仓库最显眼的位置，而不是藏在某个没人点开的 Wiki 里。文档越接近实际操作界面，就越有生命力。

不止是文档，而是“文档层级”的设计

视频中一个被很多人忽略的重点是：文档本身是有层级的。不同阶段、不同成熟度的设计系统，所需要的文档类型完全不同。

Figma 团队提到，从文件内说明，到更系统化的 CMS，再到根据具体使用场景定制的文档形式，每一层都对应着团队所处的阶段。问题不在于“有没有文档”，而在于“有没有用对层级”。

这对 AI 团队尤其致命。很多团队在还处于快速试错阶段时，就试图搭建庞大的文档体系，结果维护成本直接拖慢研发；而另一部分团队已经在支撑多人、多模型、多产品，却还停留在零散笔记阶段。Figma 给出的隐含建议是：文档和系统一样，也要按阶段进化。

从样式到组件：真正拉开差距的是“为什么这样用”

当话题从 style 转向 components，视频的重心也发生了变化。这里讨论的不再是“长什么样”，而是“为什么这么设计、应该在什么情况下使用”。

他们明确指出，组件级文档之所以影响巨大，是因为它直接决定了系统能否被正确使用。没有语义、没有使用边界的组件，只会让系统看起来很完整，用起来却一塌糊涂。

在 AI 产品和平台中，这一点几乎是原封不动地成立的。一个 API、一个 Prompt 模板、一个评估指标，如果只告诉你“怎么调”，却不告诉你“什么时候不该用”，那它迟早会被误用。好的文档不是说明书，而是决策辅助工具。

共享语言，比完美文档更重要

视频后半段提到一个非常容易被忽视、但极其关键的点：documentation 的目标之一，是建立 shared vernacular（共享语言）。

当团队对同一个概念有不同叫法、不同理解，再详尽的文档都会变成噪音。相反，一套不断被文档强化的共同语言，可以极大降低跨角色、跨团队的沟通成本。

这也是为什么他们反复强调：不要试图“重新发明轮子”。成熟的文档模式、成熟的命名方式，本身就是行业共识的沉淀。对 AI 团队而言，越早在模型、数据、评估这些核心概念上达成语言一致，后期扩张时付出的隐性成本就越低。

总结

这场关于 documentation 的分享，看似在聊设计系统，实则在讨论一个更底层的问题：复杂系统如何长期保持可协作、可演进。对 AI 从业者来说，最大的 takeaway 不是“多写点文档”，而是重新思考文档出现的位置、层级和目标。下一次你要写文档时，不妨先问三个问题：它离实际工作够近吗？它符合团队当前阶段吗？它有没有帮助建立共同语言？如果答案都是“是”，那这份文档大概率会真正被用起来。

关键词： 文档体系， 设计系统， Figma， 团队协作， AI 从业者

事实核查备注： 需要核查的视频基本信息包括：视频发布时间（2022-08-25）、频道名称（Figma Config）、视频标题（Building blocks： Diving into documentation）。文中未涉及具体人物姓名、数据或外部公司声明。