docs[patch]: Add search keyword, update contribution guide (#23602)

CC @vbarda @hinthornw
This commit is contained in:
Jacob Lee 2024-06-27 12:36:02 -07:00 committed by GitHub
parent bffc3c24a0
commit 644723adda
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 26 additions and 25 deletions

View File

@ -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). Any chain created with LCEL can be easily deployed using [LangServe](/docs/langserve).
### Runnable interface ### Runnable interface
<span data-heading-keywords="invoke"></span> <span data-heading-keywords="invoke,runnable"></span>
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. 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.

View File

@ -18,10 +18,10 @@ Under this framework, all documentation falls under one of four categories: [Tut
### Tutorials ### Tutorials
Tutorials are lessons that take the reader through a practical activity. Their purpose is to help the user 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 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, and the end result of a tutorial does not need to 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 against all cases. Information on how to address additional scenarios 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
can occur in how-to guides. belongs in how-to guides.
To quote the Diataxis website: To quote the Diataxis website:
@ -36,17 +36,17 @@ Some examples include:
Here are some high-level tips on writing a good tutorial: 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 - 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 - Be specific, not abstract and follow one path.
- No need to go deeply into alternative approaches, but its ok to reference them, ideally with a link to an appropriate how-to guide - No need to go deeply into alternative approaches, but its 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 - Get "a point on the board" as soon as possible - something the user can run that outputs something.
- You can iterate and expand afterwards - You can iterate and expand afterwards.
- Try to frequently checkpoint at given steps where the user can run code and see progress - Try to frequently checkpoint at given steps where the user can run code and see progress.
- Focus on results, not technical explanation - Focus on results, not technical explanation.
- Crosslink heavily to appropriate conceptual/reference pages - 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 - 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 - 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 - End with a recap/next steps section summarizing what the tutorial covered and future reading, such as related how-to guides.
### 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: 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 - 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 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 - Assume familiarity of concepts, but explain why suggested actions are helpful.
- Crosslink heavily to conceptual/reference pages - Crosslink heavily to conceptual/reference pages.
- Discuss alternatives and responses to real-world tradeoffs that may arise when solving a problem - Discuss alternatives and responses to real-world tradeoffs that may arise when solving a problem.
- Use lots of example code - 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 - 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 ### Conceptual guide
LangChain's conceptual guide falls under the **Explanation** quadrant of Diataxis. They should cover LangChain terms and concepts 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 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 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. 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. This guide on documentation style is meant to fall under this category.