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