diff --git a/docs/docs/concepts.mdx b/docs/docs/concepts.mdx index d811e7054a6..7ac189fe454 100644 --- a/docs/docs/concepts.mdx +++ b/docs/docs/concepts.mdx @@ -89,7 +89,7 @@ With LCEL, **all** steps are automatically logged to [LangSmith](https://docs.sm Any chain created with LCEL can be easily deployed using [LangServe](/docs/langserve). ### Runnable interface - + To make it as easy as possible to create custom chains, we've implemented a ["Runnable"](https://api.python.langchain.com/en/stable/runnables/langchain_core.runnables.base.Runnable.html#langchain_core.runnables.base.Runnable) protocol. Many LangChain components implement the `Runnable` protocol, including chat models, LLMs, output parsers, retrievers, prompt templates, and more. There are also several useful primitives for working with runnables, which you can read about below. diff --git a/docs/docs/contributing/documentation/style_guide.mdx b/docs/docs/contributing/documentation/style_guide.mdx index b4cb049bcba..b4334fb9154 100644 --- a/docs/docs/contributing/documentation/style_guide.mdx +++ b/docs/docs/contributing/documentation/style_guide.mdx @@ -18,10 +18,10 @@ 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 not cover -multiple permutations of ways to achieve that goal in-depth, and the end result of a tutorial does not need to -be completely production-ready against all cases. Information on how to address additional scenarios -can occur in how-to guides. +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 +belongs in how-to guides. To quote the Diataxis website: @@ -36,17 +36,17 @@ Some examples include: Here are some high-level tips on writing a good tutorial: -- Focus on guiding the user to get something done, but keep in mind the end-goal is more to impart principles than to create a perfect production system -- Be specific, not abstract and follow one path - - No need to go deeply into alternative approaches, but it’s ok to reference them, ideally with a link to an appropriate how-to guide -- Get "a point on the board" as soon as possible - something the user can run that outputs something - - You can iterate and expand afterwards - - Try to frequently checkpoint at given steps where the user can run code and see progress -- Focus on results, not technical explanation - - Crosslink heavily to appropriate conceptual/reference pages -- The first time you mention a LangChain concept, use its full name (e.g. "LangChain Expression Language (LCEL)"), and link to its conceptual/other documentation page - - It's also helpful to add a prerequisite callout that links to any pages with necessary background information -- End with a recap/next steps section summarizing what the tutorial covered and future reading, such as related how-to guides +- Focus on guiding the user to get something done, but keep in mind the end-goal is more to impart principles than to create a perfect production system. +- Be specific, not abstract and follow one path. + - No need to go deeply into alternative approaches, but it’s ok to reference them, ideally with a link to an appropriate how-to guide. +- Get "a point on the board" as soon as possible - something the user can run that outputs something. + - You can iterate and expand afterwards. + - Try to frequently checkpoint at given steps where the user can run code and see progress. +- Focus on results, not technical explanation. + - Crosslink heavily to appropriate conceptual/reference pages. +- The first time you mention a LangChain concept, use its full name (e.g. "LangChain Expression Language (LCEL)"), and link to its conceptual/other documentation page. + - It's also helpful to add a prerequisite callout that links to any pages with necessary background information. +- End with a recap/next steps section summarizing what the tutorial covered and future reading, such as related how-to guides. ### How-to guides @@ -66,20 +66,21 @@ Some examples include: Here are some high-level tips on writing a good how-to guide: -- Clearly explain what you are guiding the user through at the start -- Assume higher intent than a tutorial and show what the user needs to do to get that task done -- Assume familiarity of concepts, but explain why suggested actions are helpful - - Crosslink heavily to conceptual/reference pages -- Discuss alternatives and responses to real-world tradeoffs that may arise when solving a problem -- Use lots of example code -- End with a recap/next steps section summarizing what the tutorial covered and future reading, such as other related how-to guides +- Clearly explain what you are guiding the user through at the start. +- Assume higher intent than a tutorial and show what the user needs to do to get that task done. +- Assume familiarity of concepts, but explain why suggested actions are helpful. + - Crosslink heavily to conceptual/reference pages. +- Discuss alternatives and responses to real-world tradeoffs that may arise when solving a problem. +- Use lots of example code. + - Prefer full code blocks that the reader can copy and run. +- End with a recap/next steps section summarizing what the tutorial covered and future reading, such as other related how-to guides. ### 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. There should be few, if any, concrete code examples. The goal here is to -impart perspective to the user rather than to finish a practical project. +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. This guide on documentation style is meant to fall under this category.