Chinese 🇨🇳

AI 可读文档

目前，人们对一个名为GitHub Copilot的开发工具产生了很大的兴趣，它带有AI辅助功能。 似乎有一种误解认为这个工具只是为工程师而设计的。 尽管这在某种程度上是正确的，但它也是部分错误的。 的确，GitHub Copilot有着惊人的能力，可以改变工程师的工作方式。 但是，随着工程师的工作方法的变化，组织也必须适应变化。 如果你处于PM或PO的职位，这对你来说也是一个重要的问题。 因为你的团队的工程师被期望能够最快速地执行你定义的要求。 未来，即使你不是一名工程师，你也需要创建AI可读的文档，以便你的团队的工程师能够与AI进行协作。

文档文化和AI本地化开发

近年来，AI技术飞速发展，像LLM（大型语言模型）这样的模型也受到了关注。 开源开发平台GitHub也进军了AI开发领域。 一个典型的例子是“GitHub Copilot”。 有趣的是，AI辅助开发和开源开发在协作方面有共同之处。 具体而言，这两种方法都涉及到使用基于文档的格式，如Markdown。 这些格式被设计用于表示结构化信息，比如PPT或Excel文件，比起来更容易被AI分析。 因此，它们有助于提高AI生成代码的质量。

AI更喜欢简单的CSV文件，而不是充满元数据的复杂Excel电子表格。 如果你作为PM列出客户需求并收集数据库所需的信息，如果这些需求是以CSV文件的形式编写的，或者在Markdown中进行了总结，工程师就可以很容易地将它们转换为代码。 然而，如果你将信息编译成适合你自己的Excel文档，工程师就必须先复制、格式化，然后再将其转换为代码。 哪种方法更好？

此外，在开源开发中，文档质量与项目成功直接相关。 开源项目是向任何人开放的，良好维护的文档可以让新开发人员更轻松地加入其中。 因此，在开源开发中，文档被高度重视。 同样地，在AI开发中，良好的文档文化可以导致更高效和更高质量的开发。 即使你不是一名工程师，你在Markdown中编写的自然语言可以显著地对最终的输出，即代码，做出贡献。 这可以是代表业务逻辑的代码，表定义，甚至是测试场景。 你的开发团队准备好包括AI了吗？准备好AI可读的文档了吗？如果答案是否定的，你必须开始创建一个舒适与AI参与的开发团队。

AI本地化开发和内源战略

我们一直在讨论开源开发，但也有一个类似的概念叫做内源。 内源是采用开源软件开发的最佳实践的方法，用于开发非开源或专有软件的组织内。 它旨在促进组织边界之间的协作，打破组织的孤立。

内源对于企业避免重复造轮子、简化开发以降低成本以及通过协作创造新价值变得越来越重要。

正如在AI本地化开发页面上提到的那样，AI倾向于增强有经验的人类。 组织内了解架构的高级或有经验的个人受到提升，而其他人则被分配更简单的任务。

然而，由于AI主要受到来自互联网的知识培训，它无法访问专有域、组织内部的封闭知识或未公开的信息。 因此，如果这些信息没有得到记录或在组织内得到适当的共享，就会产生问题。 这个问题意味着不仅工程师不能访问这些信息，而且像GitHub Copilot这样的AI也不能访问它。

当前，无法从互联网上获得的知识正在变得越来越重要，也成为企业的核心竞争力。 在O'Reilly的内源入门书《入门内源》中有一句引文：

内源与经典开源不同之处在于，它仍处于单个组织的视野和控制之下。 项目的“开放性”延伸到组织中的许多团队。 这使得组织可以将区分性的商业机密嵌入到代码中，而不用担心会被外部人员揭露，同时又从组织内部贡献人员的创造力和多样化的视角中获益。

许多企业面临的选择是与AI合作还是被AI替代。 将组织的竞争优势源泉聚合起来，并让AI利用它，是至关重要的。 为了实现这一点，具有AI可读性的文档是必不可少的。

关于内源，已经存在一个成熟的社区，分享了在组织内实现共同创作和创建文档的方法。 访问这个社区并利用内源倡议。 通过这样做，你可以有效地利用内部知识和信息，并充分利用与AI的协作。

内源参考资料

创建上下文丰富的文档

随着开源开发的成熟，跨国和跨时区的合作开始出现。然而，地理距离和时差有时会使同步通信变得困难。例如，在纽约白天是东京的晚上，晚上打扰生活在日本的贡献者或干扰他们的家庭时间是不可取的。因此，基于书面文件的文档通常更受欢迎。这可以是类似于 RFC 或设计文档，或者是在 GitHub 问题中编写的评论。在问题评论中形成的文档也称为“被动文档”。这些也是文档的形式。

《理解内源清单》（O'Reilly 出版）中有一段话，大意如下：

被动文档是我们每天在公开交流时创建的文档记录。它是摆脱信息孤岛、将知识形成存档并易于查找的好方法。作为额外的奖励，它通常与项目或代码一起保存，因此它位于易于找到、与上下文相关的位置。

重要的是要适当地用语言表达出来，包括上下文。通过 Zoom 或面对面异步跨时区交谈传达的非语言交流、细微差别和氛围都很难传达。

考虑与 AI 协作开发。例如，GitHub Copilot 是否会参加 Zoom 会议？它会在团队房间里说：“嘿，我是 GitHub Copilot，让我们来一次快速的汇报会议”吗？答案是否定的。所有上下文必须以书面形式传达给 AI。这也是在开源开发等异步通信情况下创建适当文档所必需的。

当然，开源开发和 AI 协助开发之间的文档粒度有所不同。在 GitHub 问题中写下“我想修复这个 bug”可能会促使其他人想到解决方案，但 AI 无法做到这一点。然而，AI 确实擅长某些方面。如果你想将云架构表示为基础设施即代码，最好是用 Mermaid 编写或用自然语言表达，而不是在 PowerPoint 中绘制。

重点不在于需要将所有交流都记录下来。你和你的团队需要考虑留下什么级别的文档，以及如何以及在哪里留下。

人工智能协调组织知识

GitHub Copilot X中包括的GitHub Copilot for Docs等功能，使得人工智能可以为您创建完美的文档。 您编写的文档也可以成为下一位使用者的入门资料。 过去，收集信息和为新工程师创建入门资料是常见任务，但未来，人工智能可能会承担这个角色。 您可以将所有知识嵌入文档中，作为唯一可靠的信息来源。 这种方法也在Atlassian文档中明确地体现出来。 以AI本地开发为背景阅读他们的文档可能会带来新的发现。 您编写的文档将通过人工智能拥有一种个性化的感觉。 然而，正如前面提到的，这需要足够的文档记录。

自然语言与实现之间的距离变得更近了

您可能已经注意到了，自然语言和实现之间的距离正在变得更近。 正如前面提到的，从教育角度来看，如果将编写提示和代码放在同一个位置，可能可以创建单个文件中的文档。 这种变化是很有趣的。

检查清单

Last updated