文档风格指南
随着 LangChain 的不断发展，覆盖其所需的文档范围也在不断扩大。本页为所有为 LangChain 编写文档的人员提供指南，以及我们围绕组织和结构的一些理念。
理念
LangChain 的文档遵循 Diataxis 框架。在这个框架下，所有文档都属于以下四类之一：教程、操作指南、参考 和 解释。
教程
教程是带读者完成实际活动的课程。它们的目的是帮助用户通过展示一种以动手的方式完成某些目标的方法，来帮助用户理解概念及其相互作用。它们应该避免深入介绍完成该目标的多种方法。相反，它应该指导新用户完成一条完成教程目标的推荐路径。虽然教程的最终结果不一定需要完全准备好投入生产，但它应该是有用的，并能实际满足你在教程引言中明确说明的目标。有关如何解决其他场景的信息属于操作指南。
引用 Diataxis 网站
教程为用户的技能和知识获取——他们的学习服务。它的目的不是帮助用户完成某件事，而是帮助他们学习。
在 LangChain 中，这些通常是展示端到端用例的高级指南。
一些例子包括
一个好的结构性经验法则，是遵循这个来自 NumPy 的 示例 的结构。
以下是一些关于编写高质量教程的高级技巧
- 专注于指导用户完成某件事，但请记住，最终目标更多是传授原则，而不是创建完美的生产系统。
- 具体，而不是抽象，并遵循一条路径。
- 无需深入讨论其他方法，但可以参考它们，最好是提供指向适当操作指南的链接。
- 尽快“在板上得分”——用户可以运行并输出一些东西的东西。
- 你可以在之后迭代和扩展。
- 尝试在给定的步骤中频繁设置检查点，以便用户可以运行代码并查看进度。
- 专注于结果，而不是技术解释。
- 与相关的概念/参考页面进行大量交叉链接。
- 首次提及 LangChain 概念时，请使用其全名（例如，“LangChain 表达式语言 (LCEL)”），并链接到其概念/其他文档页面。
- 添加一个先决条件提示，链接到任何包含必要背景信息的页面也很有用。
- 以一个总结教程内容和未来阅读（例如相关操作指南）的摘要/下一步部分结束。
操作指南
操作指南顾名思义，演示如何执行一些离散的特定操作。它应该假设用户已经熟悉底层概念，并且正在尝试解决一个直接问题，但仍然应该提供一些背景信息或列出包含的信息可以相关的场景。它们可以并且应该讨论替代方案，如果一种方法在某些情况下可能优于另一种方法。
引用 Diataxis 网站
操作指南为已经熟练的用户服务，你可以假设他们知道自己想做什么，并且能够正确地遵循你的指示。
一些例子包括
以下是一些关于编写高质量操作指南的高级技巧
- 在开始时明确解释你正在指导用户完成的操作。
- 假设比教程更高的意图，并展示用户需要执行的操作来完成该任务。
- 假设熟悉概念，但解释为什么建议的操作会有所帮助。
- 与相关的概念/参考页面进行大量交叉链接。
- 讨论在解决问题时可能出现的现实世界权衡的替代方案和响应。
- 使用大量示例代码。
- 优先考虑读者可以复制和运行的完整代码块。
- 以一个总结教程内容和未来阅读（例如其他相关操作指南）的摘要/下一步部分结束。
概念指南
LangChain 的概念指南属于 Diataxis 的解释象限。它们应该以比操作指南或教程更抽象的方式涵盖 LangChain 术语和概念，并且应该面向对深入了解框架感兴趣的好奇用户。尝试避免过大的代码示例——这里的目标是向用户传达视角，而不是完成一个实际项目。这些指南应该涵盖为什么事物按它们的方式工作。
本篇关于文档风格的指南应该属于此类别。
引用 Diataxis 网站
解释的角度高于并且更广阔，不同于其他类型。它不像操作指南那样从用户的视角出发，也不像参考材料那样近距离观察机制。它在每种情况下涵盖的范围都是一个主题——“知识领域”，该主题在某种程度上必须以合理且有意义的方式进行界定。
一些例子包括
以下是一些关于编写高质量概念指南的高级技巧
- 解释设计决策。为什么存在概念 X 以及为什么以这种方式设计它？
- 使用类比并参考其他概念和替代方案
- 避免混合过多的参考内容
- 你可以并且应该参考其他指南中涵盖的内容，但请确保链接到它们
参考
参考包含详细的低级信息，描述了确切存在的哪些功能以及如何使用它们。在 LangChain 中，这主要指我们的 API 参考页面，它们是从代码中的 docstring 生成的。参考页面通常不会从头到尾阅读，而是在用户需要了解特定内容的使用方式时才查阅。
引用 Diataxis 网站
参考指南的唯一目的是尽可能简洁地以有序的方式进行描述。虽然教程和操作指南的内容由用户的需求引导，但参考材料由它描述的产品引导。
LangChain 中的许多参考页面都是从代码中自动生成的，但以下是一些关于编写高质量 docstring 的高级技巧
- 简洁
- 讨论特殊情况和与用户预期之间的偏差
- 详细介绍所需的输入和输出
- 关于何时可以使用该功能的简要说明是可以的，但深入的细节属于其他部分。
每个类别都服务于不同的目的，并且需要对编写和组织内容采用特定方法。
一般指南
以下是一些在编写和组织文档时应考虑的其他指南。
我们通常不会在没有迫切需要的情况下合并来自外部贡献者的新教程。我们欢迎更新以及新的集成文档、操作指南和参考。
避免重复
涵盖相同内容的多个页面难以维护，并会导致混淆。对于给定的概念或功能，应该只有一个（很少有几个）规范页面。相反，你应该链接到其他指南。
链接到其他部分
因为文档的部分并非孤立存在，所以尽可能链接到其他部分以使开发人员能够在行内了解更多关于未知主题的信息非常重要。
这包括链接到 API 参考以及概念部分！
简洁
总的来说，采用少即是多的方法。如果已经存在一个带有良好概念解释的部分，你应该链接到它，而不是重新解释它，除非你所记录的概念提出了一些新的问题。
简洁，包括在代码示例中。
通用风格
- 尽可能使用主动语态和现在时
- 使用示例和代码片段来说明概念和用法
- 使用适当的标题级别（
#、##、###等）以分层方式组织内容 - 使用更少的单元格，包含更多代码，以便更容易复制和粘贴
- 使用项目符号和编号列表将信息分解为易于理解的块
- 经常使用表格（尤其是参考部分）和图表以视觉方式呈现信息
- 为较长的文档页面包含目录以帮助读者浏览内容，但为较短的页面隐藏目录