宝软数字 · 产品设计哲学 · 2026-01-20
在软件工程领域，文档和技术写作常常被视为"二等公民"——代码是第一位的，功能是第一位的，文档不过是锦上添花的东西，等有空了再补。这种心态造成了一个普遍现象：绝大多数软件产品的文档要么残缺不全，要么已经严重过时，要么是写给搜索引擎看而不是写给人看的。
我们在EIOS的产品建设中采取了一种截然相反的立场：文档不是功能的附属品，文档本身就是产品的一部分。在我们的发布流程中，一个功能的"完成"不是以代码合并到主分支为标志，而是以配套文档经过审核并上线为标志。如果一个新Agent的功能代码写完了但文档还没写完，这个功能就不能被标记为"已上线"。这不是为了文档而文档，而是我们对"功能完成"的定义就包含了文档。
这篇文章将完整阐述我们的文档哲学——为什么用文档完成度作为功能上线的硬性标准，以及这一做法对产品质量、客户体验和团队效率的深远影响。
一个功能被开发出来但没有人知道怎么使用，这个功能存在吗？从工程交付的角度来说，存在。代码在那里，服务器在运行，数据库在存储。但从用户价值的角度来说，不存在。用户不知道它存在，不知道它能干什么，不知道怎么用它，不知道它和别的功能之间是什么关系——这个功能在用户的认知世界中没有对应的位置。
在企业级B2B产品中，这个问题尤其致命。EIOS的客户不是个人消费者，他们不会花一个下午去"探索"你的产品有哪些功能。他们是企业管理者，是部门负责人，是数据分析师，时间是他们最稀缺的资源。当一个新功能上线但没有配套的文档来解释它时，这个功能在客户面前就像一个上锁的房间——门上没有标签，不知道里面是什么，也没有钥匙。
更糟糕的是，没有文档的功能会制造"幽灵流量"。客户可能在日常使用中偶然发现了这个功能入口，尝试使用但因为不理解其设计意图而得到不符合预期的结果，然后产生"这功能不好用"的判断。这个判断一旦形成，即使后来补上了完善的文档也很难扭转。第一印象的破坏力远超后期弥补的能力。
我们内部有一个数据指标叫"功能认知率"——指的是在功能上线一个月内，有多少比例的适用客户（即该功能确实对他们有使用价值的客户）至少尝试使用过一次该功能。在引入"文档完成才上线"的纪律之前，这个指标徘徊在30%左右。引入之后，飙升到了接近70%。根本原因很简单：文档让功能对用户变得可见、可理解和可信任。
当文档成为功能上线的硬性标准时，它反向塑造了开发流程本身。在我们的实践中，文档不是开发完成后再写的，而是和功能设计同步开始的。当一个新功能的需求确定后，产品经理和文档工程师（这是我们团队中的一个专门角色，后面会详细讲）就开始一起编写功能文档的初稿——包括使用场景、操作步骤、输入输出格式、常见问题。
这个"提前写文档"的做法有一个意想不到的礼物效应：写文档的过程本身就是在验证设计方案的完整性和清晰度。当你试图用清晰的文字向用户解释"这个Agent可以用来做什么，怎么用，能处理什么样的输入，会产生什么样的输出"时，你会发现设计方案中那些模糊的、不完整的、自相矛盾的地方。这些在代码层面可能要到测试阶段才会暴露的问题，在设计文档阶段就会被发现和修复。
举一个真实的例子。我们在设计制造业供应商评估Agent时，产品经理最初在PRD中写道："输入供应商名称，系统自动评估该供应商的综合表现。"这句话在PRD里看起来没问题。但当文档工程师开始写用户文档时，一个简单的问题就暴露了设计的模糊性："如果客户输入的是一个简称而不是全称怎么办？比如客户输入'浙大网新'而不是'浙江浙大网新集团有限公司'？"
这个问题在产品设计阶段完全没人想过。因为文档工程师站在用户的视角写文档，她天然会问那些产品经理在抽象设计阶段不会问到的具体问题。最终，这个追问推动了我们在Agent中增加了模糊匹配和企业名称归一化的能力——如果文档工程师是在功能开发完成后再写文档，这个能力的缺失会直到用户反馈时才会被发现。
文档写作是产品设计完整度的终极检验。当你能用清晰、准确、无歧义的语言向一个没有背景知识的新用户解释清楚一个功能的所有方面时，这个功能的设计才是真正完成的。否则，那些在文档写作中暴露出来的模糊地带，迟早会在用户使用中暴露出来——只是代价会大得多。
在大多数科技公司中，文档写作是产品经理或工程师的"附加任务"——"你做完功能顺便把文档也写一下"。这种做法的问题在于，好的文档写作和好的产品设计、好的编程是完全不同的能力。一个优秀的工程师不一定能写出普通人能看懂的文档，就像一个优秀的作家不一定能读懂代码。
我们在EIOS团队中设置了专职的文档工程师角色。这不是一个传统的"技术写作"岗位——不只是负责把工程师写的草稿润色成通顺的中文。我们的文档工程师深度参与产品设计过程，从用户视角审视功能的完整性和逻辑性，在功能上线前就确保文档的质量和功能的用户就绪度。
文档工程师的核心能力不是文笔（虽然文笔好也有帮助），而是换位思考的能力——能够暂时忘记自己对产品的了解和熟悉，站在一个第一次接触这个功能的用户的视角来理解和使用产品。这种能力说起来简单做起来极难，因为"知识的诅咒"是人类大脑的固有限制——一旦你知道了某件事，你就很难想象不知道这件事是什么感觉。文档工程师的专业就在于此：系统地对抗知识的诅咒，确保产品的信息传递不依赖用户已经知道任何东西。
文档工程师的另一个关键职能是维护文档信息架构的一致性。当一个产品有几十上百篇功能文档时，如何组织它们、如何让用户快速找到所需的信息、如何确保不同文档之间的术语统一和逻辑连贯——这些不是写完一篇扔到网上就能解决的问题。我们的文档工程师维护着一套完整的文档信息架构，确保EIOS的文档体系是有机的、可导航的、逻辑自洽的，而不是一堆孤立文章的堆砌。
"文档"不是一个单一的东西。同一个功能，对于第一次接触的CEO、每天使用的数据分析师、需要做技术集成的IT工程师和需要做故障排查的运维人员来说，他们需要的文档内容和形式完全不同。把一个功能的所有信息塞进同一篇文档里，结果是谁都找不到自己需要的部分。
EIOS的文档体系分为四个层次，每一层面向不同的读者，解决不同的问题。
第一层：场景文档。面向决策者和新用户。回答"这个功能能帮我解决什么业务问题？"。用业务场景而非技术术语来描述功能价值，包含典型的"使用前vs使用后"的对比案例。一个CEO不需要知道某个分析算法叫什么名字，他需要知道的是"用了这个功能，我的库存周转率能提升多少"。
第二层：操作文档。面向日常使用者。回答"怎么使用这个功能？"。用步骤化的方式描述操作流程，每一步配截图或录屏，标注关键的操作技巧和常见错误。一个销售主管不需要知道这个功能背后的数据模型，他需要知道他输入什么就能得到他想要的客户分析。
第三层：技术文档。面向开发者和系统集成人员。回答"这个功能的技术规格是什么？"。包括API端点定义、请求和响应格式、数据模型、认证方式、速率限制、错误码对照。这是整个文档体系中最需要精确性和完整性的部分。
第四层：故障排除文档。面向遇到问题的任何用户。回答"当出现XX问题时怎么办？"。不按功能分类，而是按问题现象分类——"为什么我的日报没有数据？""为什么Agent分析结果和我预期的不一样？"——然后给出诊断步骤和解决方案。这一层的文档应该是活的、持续更新的，每一个新的客户支持案例都有可能转化为一个故障排除文档条目。
文档的好坏不在于字数多少，而在于正确的人在正确的时间找到正确的信息。四层文档架构的本质是一种信息分区策略——不让CEO和技术文档搏斗，也不让开发者靠读营销文案来集成API。
写一篇好文档难，让一百篇文档长期保持准确更难。软件产品在不断迭代，功能在不断变化，界面在持续更新。当一个功能更新后，如果对应的文档没有同步更新，这个文档就从一个"有帮助的资源"变成了一个"误导用户的信息陷阱"。过时的文档比没有文档更糟糕——没有文档用户会来问你，过时的文档用户会照做然后出错。
我们为文档维护建立了两条纪律。第一条是"谁改代码谁更新文档"。这听起来像是理所当然的，但在很多团队中并不被执行。工程师修改了一个API的响应格式，但认为"更新文档是文档工程师的事情"——结果就是代码和文档的持续偏离。在EIOS，任何一个功能或API的变更，对应的文档更新和代码修改必须包含在同一个提交（或者同一个版本的发布包）中。不更新的代码上线算生产事故，不上线的文档过期也算。
第二条是"定期全量审查"。即使有了"谁改谁更"的纪律，仍然会有遗漏的角落。我们每季度进行一次全量文档审查——文档工程师按照文档清单逐篇检查，打开对应的功能实际使用一遍，验证文档中的每一个步骤、每一张截图、每一个API响应示例是否与当前产品实际情况一致。发现的偏差登记为文档Bug，按照与代码Bug同等的优先级排期修复。
我们还在探索文档质量的自动化检测手段。比如，能否通过自动化测试框架来验证API文档中的请求和响应示例是否与实际的API行为一致？能否通过对比文档中引用的界面截图与实际的页面截图来检测UI变更导致的文档过期？这些自动化手段目前还不成熟，但随着我们文档规模的扩大，它们是维持文档质量的必要投资。
在B2B产品的增长策略中，文档很少被视为一个增长杠杆。大家讨论的是SEO、内容营销、销售漏斗、渠道建设。但在我们看来，优质的文档是B2B产品最被低估的增长引擎之一。
首先，文档驱动有机搜索获客。当一家企业的IT管理员在搜索引擎上输入"如何用AI分析制造业供应链风险"时，如果EIOS的文档排名靠前且内容真正有用，这篇文章就完成了一次高质量的触达。与广告或内容营销文章不同的是，通过文档来到你网站的访客已经是带着明确的使用意图的——他们在搜索一个具体问题的答案，而你的文档直接提供了这个答案。这种高质量的访客转化率远高于任何泛流量。
其次，文档降低了销售和客户成功的成本。在B2B销售中，潜在客户经常会问很多技术问题——"你们的Agent怎么对接我们的ERP系统？""数据同步的频率可以设多少？""分析结果的API是什么样的？"如果这些问题没有文档可查，销售需要反复把技术团队拉进客户会议中，消耗了最稀缺的工程资源。而一个完备的文档体系可以让销售直接发送相关链接，客户自助获取答案，把技术团队从重复性的售前答疑中解放出来。
第三，文档提升了客户留存。一个企业客户在使用产品过程中遇到一个操作问题，他有两个选择：翻找你的文档自己解决，或者提交一个技术支持工单等回复。如果他很快在文档中找到了答案，一切顺利。如果他找不到，不得不提交工单然后等半天到一天才收到回复——他的体验已经打了折扣。多次累积之后，即使产品功能本身没问题，不良的支持体验也足以推动他寻找替代品。文档是客户支持的前置防线，每节省一次技术支持介入，就多保住一分客户满意度。
把文档视为产品而非附属品，这是一个看似微小实则深远的认知转变。它意味着文档的设计、撰写、维护和优化都会得到与产品核心功能同等的资源和重视。也是因为我们坚信：一个连文档都不愿意认真写的产品团队，不可能做出真正优秀的产品。