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