Skip to content

Commit

Permalink
English Update and fixed a duplicate "the" (#27981)
Browse files Browse the repository at this point in the history
Fixed a duplicate "the" in the documentation and made the documentation
generally easier to understand
  • Loading branch information
DangerousPotential authored Nov 13, 2024
1 parent f6d3458 commit 4b641f8
Showing 1 changed file with 15 additions and 15 deletions.
30 changes: 15 additions & 15 deletions docs/docs/contributing/how_to/documentation/style_guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ sidebar_class_name: "hidden"

# Documentation Style Guide

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
As LangChain continues to grow, the amount of documentation required to cover the various concepts and integrations continues to grow too.
This page provides guidelines for anyone writing documentation for LangChain and outlines some of our philosophies around
organization and structure.

## Philosophy
Expand All @@ -18,9 +18,9 @@ Under this framework, all documentation falls under one of four categories: [Tut
### Tutorials

Tutorials are lessons that take the reader through a practical activity. Their purpose is to help the user
gain understanding of concepts and how they interact by showing one way to achieve some goal in a hands-on way. They should **avoid** giving
multiple permutations of ways to achieve that goal in-depth. Instead, it should guide a new user through a recommended path to accomplishing the tutorial's goal. While the end result of a tutorial does not necessarily need to
be completely production-ready, it should be useful and practically satisfy the the goal that you clearly stated in the tutorial's introduction. Information on how to address additional scenarios
gain an understanding of concepts and how they interact by showing one way to achieve a specific goal in a hands-on manner. They should **avoid** giving
multiple permutations of ways to achieve that goal in-depth. Instead, it should guide a new user through a recommended path to accomplish the tutorial's goal. While the end result of a tutorial does not necessarily need to
be completely production-ready, it should be useful and practically satisfy the goal that is clearly stated in the tutorial's introduction. Information on how to address additional scenarios
belongs in how-to guides.

To quote the Diataxis website:
Expand Down Expand Up @@ -53,8 +53,8 @@ Here are some high-level tips on writing a good tutorial:
### How-to guides

A how-to guide, as the name implies, demonstrates how to do something discrete and specific.
It should assume that the user is already familiar with underlying concepts, and is trying to solve an immediate problem, but
should still give some background or list the scenarios where the information contained within can be relevant.
It should assume that the user is already familiar with underlying concepts, and is focused on solving an immediate problem. However,
it should still provide some background or list certain scenarios where the information may be relevant.
They can and should discuss alternatives if one approach may be better than another in certain cases.

To quote the Diataxis website:
Expand All @@ -79,10 +79,10 @@ Here are some high-level tips on writing a good how-to guide:

### Conceptual guide

LangChain's conceptual guide falls under the **Explanation** quadrant of Diataxis. They should cover LangChain terms and concepts
in a more abstract way than how-to guides or tutorials, and should be geared towards curious users interested in
gaining a deeper understanding of the framework. Try to avoid excessively large code examples - the goal here is to
impart perspective to the user rather than to finish a practical project. These guides should cover **why** things work they way they do.
LangChain's conceptual guide falls under the **Explanation** quadrant of Diataxis. These guides should cover LangChain terms and concepts
in a more abstract way than how-to guides or tutorials, targeting curious users interested in
gaining a deeper understanding and insights of the framework. Try to avoid excessively large code examples as the primary goal is to
provide perspective to the user rather than to finish a practical project. These guides should cover **why** things work they way they do.

This guide on documentation style is meant to fall under this category.

Expand Down Expand Up @@ -137,14 +137,14 @@ be only one (very rarely two), canonical pages for a given concept or feature. I

### Link 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.
Because sections of the docs do not exist in a vacuum, it is important to link to other sections frequently,
to allow a developer to learn more about an unfamiliar topic within the flow of reading.

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

### Be concise

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
In general, take a less-is-more approach. If another section with a good explanation of a concept 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.
Expand Down

0 comments on commit 4b641f8

Please sign in to comment.