diff --git a/docs/docs/contributing/how_to/documentation/style_guide.mdx b/docs/docs/contributing/how_to/documentation/style_guide.mdx index 437977573c09f..2eb20d6853786 100644 --- a/docs/docs/contributing/how_to/documentation/style_guide.mdx +++ b/docs/docs/contributing/how_to/documentation/style_guide.mdx @@ -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 @@ -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: @@ -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: @@ -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. @@ -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.