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