## LangChain Documentation Style Guide

## Introduction[​](#introduction "Direct link to Introduction")

As LangChain continues to grow, the surface area of documentation required to cover it continues to grow too. This page provides guidelines for anyone writing documentation for LangChain, as well as some of our philosophies around organization and structure.

## Philosophy[​](#philosophy "Direct link to Philosophy")

LangChain's documentation aspires to follow the [Diataxis framework](https://diataxis.fr/). Under this framework, all documentation falls under one of four categories:

*   **Tutorials**: Lessons that take the reader by the hand through a series of conceptual steps to complete a project.
    *   An example of this is our [LCEL streaming guide](https://python.langchain.com/docs/expression_language/streaming/).
    *   Our guides on [custom components](https://python.langchain.com/docs/modules/model_io/chat/custom_chat_model/) is another one.
*   **How-to guides**: Guides that take the reader through the steps required to solve a real-world problem.
    *   The clearest examples of this are our [Use case](https://python.langchain.com/docs/use_cases/) quickstart pages.
*   **Reference**: Technical descriptions of the machinery and how to operate it.
    *   Our [Runnable interface](https://python.langchain.com/docs/expression_language/interface/) page is an example of this.
    *   The [API reference pages](https://api.python.langchain.com/) are another.
*   **Explanation**: Explanations that clarify and illuminate a particular topic.
    *   The [LCEL primitives pages](https://python.langchain.com/docs/expression_language/primitives/sequence/) are an example of this.

Each category serves a distinct purpose and requires a specific approach to writing and structuring the content.

## Taxonomy[​](#taxonomy "Direct link to Taxonomy")

Keeping the above in mind, we have sorted LangChain's docs into categories. It is helpful to think in these terms when contributing new documentation:

### Getting started[​](#getting-started "Direct link to Getting started")

The [getting started section](https://python.langchain.com/docs/get_started/introduction/) includes a high-level introduction to LangChain, a quickstart that tours LangChain's various features, and logistical instructions around installation and project setup.

It contains elements of **How-to guides** and **Explanations**.

### Use cases[​](#use-cases "Direct link to Use cases")

[Use cases](https://python.langchain.com/docs/use_cases/) are guides that are meant to show how to use LangChain to accomplish a specific task (RAG, information extraction, etc.). The quickstarts should be good entrypoints for first-time LangChain developers who prefer to learn by getting something practical prototyped, then taking the pieces apart retrospectively. These should mirror what LangChain is good at.

The quickstart pages here should fit the **How-to guide** category, with the other pages intended to be **Explanations** of more in-depth concepts and strategies that accompany the main happy paths.

note

The below sections are listed roughly in order of increasing level of abstraction.

### Expression Language[​](#expression-language "Direct link to Expression Language")

[LangChain Expression Language (LCEL)](https://python.langchain.com/docs/expression_language/) is the fundamental way that most LangChain components fit together, and this section is designed to teach developers how to use it to build with LangChain's primitives effectively.

This section should contains **Tutorials** that teach how to stream and use LCEL primitives for more abstract tasks, **Explanations** of specific behaviors, and some **References** for how to use different methods in the Runnable interface.

### Components[​](#components "Direct link to Components")

The [components section](https://python.langchain.com/docs/modules/) covers concepts one level of abstraction higher than LCEL. Abstract base classes like `BaseChatModel` and `BaseRetriever` should be covered here, as well as core implementations of these base classes, such as `ChatPromptTemplate` and `RecursiveCharacterTextSplitter`. Customization guides belong here too.

This section should contain mostly conceptual **Tutorials**, **References**, and **Explanations** of the components they cover.

note

As a general rule of thumb, everything covered in the `Expression Language` and `Components` sections (with the exception of the `Composition` section of components) should cover only components that exist in `langchain_core`.

### Integrations[​](#integrations "Direct link to Integrations")

The [integrations](https://python.langchain.com/docs/integrations/platforms/) are specific implementations of components. These often involve third-party APIs and services. If this is the case, as a general rule, these are maintained by the third-party partner.

This section should contain mostly **Explanations** and **References**, though the actual content here is more flexible than other sections and more at the discretion of the third-party provider.

note

Concepts covered in `Integrations` should generally exist in `langchain_community` or specific partner packages.

### Guides and Ecosystem[​](#guides-and-ecosystem "Direct link to Guides and Ecosystem")

The [Guides](https://python.langchain.com/docs/guides/) and [Ecosystem](https://python.langchain.com/docs/langsmith/) sections should contain guides that address higher-level problems than the sections above. This includes, but is not limited to, considerations around productionization and development workflows.

These should contain mostly **How-to guides**, **Explanations**, and **Tutorials**.

### API references[​](#api-references "Direct link to API references")

LangChain's API references. Should act as **References** (as the name implies) with some **Explanation**\-focused content as well.

## Sample developer journey[​](#sample-developer-journey "Direct link to Sample developer journey")

We have set up our docs to assist a new developer to LangChain. Let's walk through the intended path:

*   The developer lands on [https://python.langchain.com](https://python.langchain.com/), and reads through the introduction and the diagram.
*   If they are just curious, they may be drawn to the [Quickstart](https://python.langchain.com/docs/get_started/quickstart/) to get a high-level tour of what LangChain contains.
*   If they have a specific task in mind that they want to accomplish, they will be drawn to the Use-Case section. The use-case should provide a good, concrete hook that shows the value LangChain can provide them and be a good entrypoint to the framework.
*   They can then move to learn more about the fundamentals of LangChain through the Expression Language sections.
*   Next, they can learn about LangChain's various components and integrations.
*   Finally, they can get additional knowledge through the Guides.

This is only an ideal of course - sections will inevitably reference lower or higher-level concepts that are documented in other sections.

## Guidelines[​](#guidelines "Direct link to Guidelines")

Here are some other guidelines you should think about when writing and organizing documentation.

### Linking to other sections[​](#linking-to-other-sections "Direct link to Linking to other sections")

Because sections of the docs do not exist in a vacuum, it is important to link to other sections as often as possible to allow a developer to learn more about an unfamiliar topic inline.

This includes linking to the API references as well as conceptual sections!

### Conciseness[​](#conciseness "Direct link to Conciseness")

In general, take a less-is-more approach. If a section with a good explanation of a concept already exists, you should link to it rather than re-explain it, unless the concept you are documenting presents some new wrinkle.

Be concise, including in code samples.

### General style[​](#general-style "Direct link to General style")

*   Use active voice and present tense whenever possible.
*   Use examples and code snippets to illustrate concepts and usage.
*   Use appropriate header levels (`#`, `##`, `###`, etc.) to organize the content hierarchically.
*   Use bullet points and numbered lists to break down information into easily digestible chunks.
*   Use tables (especially for **Reference** sections) and diagrams often to present information visually.
*   Include the table of contents for longer documentation pages to help readers navigate the content, but hide it for shorter pages.