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