diff --git a/docs/docs/contributing/how_to/documentation/style_guide.mdx b/docs/docs/contributing/how_to/documentation/style_guide.mdx index c9e0970f0f9..45f4126d3e0 100644 --- a/docs/docs/contributing/how_to/documentation/style_guide.mdx +++ b/docs/docs/contributing/how_to/documentation/style_guide.mdx @@ -79,7 +79,7 @@ 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. These guides should cover LangChain terms and concepts +LangChain's conceptual guides fall 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 the way they do. @@ -105,7 +105,7 @@ Here are some high-level tips on writing a good conceptual guide: ### References References contain detailed, low-level information that describes exactly what functionality exists and how to use it. -In LangChain, this is mainly our API reference pages, which are populated from docstrings within code. +In LangChain, these are mainly our API reference pages, which are populated from docstrings within code. References pages are generally not read end-to-end, but are consulted as necessary when a user needs to know how to use something specific. @@ -127,17 +127,17 @@ Each category serves a distinct purpose and requires a specific approach to writ Here are some other guidelines you should think about when writing and organizing documentation. -We generally do not merge new tutorials from outside contributors without an actue need. +We generally do not merge new tutorials from outside contributors without an acute need. We welcome updates as well as new integration docs, how-tos, and references. ### Avoid duplication Multiple pages that cover the same material in depth are difficult to maintain and cause confusion. There should -be only one (very rarely two), canonical pages for a given concept or feature. Instead, you should link to other guides. +be only one (very rarely two) canonical pages for a given concept or feature. Instead, you should link to other guides. ### Link to other sections -Because sections of the docs do not exist in a vacuum, it is important to link to other sections frequently, +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 and conceptual sections!