mirror of
https://github.com/hwchase17/langchain
synced 2024-11-10 01:10:59 +00:00
docs[patch]: Add search keyword, update contribution guide (#23602)
CC @vbarda @hinthornw
This commit is contained in:
parent
bffc3c24a0
commit
644723adda
@ -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
|
||||
<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.
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user