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