@ -10,16 +10,15 @@ Why are these changes necessary? How do they improve the cookbook?
## For new content
When contributing new content, make sure to read through our [contributions rubric](/project/rubric.md) before submitting, and complete the following action items:
When contributing new content, read through our [contribution guidelines](/CONTRIBUTING.md), and mark the following action items as completed:
- [ ] I have added a new entry in [registry.yaml](/registry.yaml) so that my content renders on the cookbook website.
- [ ] I have conducted a self-review of my content based on the [contributions rubric](/project/rubric.md):
- [ ] Relevance: This content is related to building with the OpenAI API.
- [ ] I have conducted a self-review of my content based on the [c](/CONTRIBUTING.md#rubric):
- [ ] Relevance: This content is related to building with OpenAI technlogies and is useful to others.
- [ ] Uniqueness: I have searched for related examples in the OpenAI Cookbook, and verified that my content offers new insights or unique information compared to existing documentation.
- [ ] Spelling and Grammar: I have checked for spelling or grammatical mistakes.
- [ ] Clarity and Comprehensibility: I have done a final read-through and verified that the content is easy to understand.
- [ ] Accuracy and Correctness: The information I include is correct, appropriately cited, and all of my code executes successfully.
- [ ] Usability: I have verified that the content and code is well organized and easy to navigate and use.
- [ ] Completeness: I have verified that my content thorough and detailed, and I have explained everything fully.
- [ ] Clarity: I have done a final read-through and verified that my submission is well-organized and easy to understand.
- [ ] Correctness: The information I include is correct and all of my code executes successfully.
- [ ] Completeness: I have explained everything fully, including all necessary references and citations.
Remember, we will rate each of these areas on a scale from 1 to 5, with 1 being the lowest and 5 being the highest. Aim for a score of 3 or higher in each area to increase the chances of your contribution being accepted. Refer to our [contributions rubric](/project/rubric.md) for more details.
We will rate each of these areas on a scale from 1 to 4, and will only accept contributions that score 3 or higher on all areas. Refer to our [contributions guidelines](/CONTRIBUTING.md) for more details.
@ -4,17 +4,18 @@ The OpenAI Cookbook is a community-driven resource aimed at sharing knowledge in
Before contributing, read through the existing issues and pull requests to see if someone else is already working on something similar. That way you can avoid duplicating efforts.
## What makes a good cookbook?
## What makes a good contribution?
**Useful:** Involves concepts or techniques that can be applied broadly, and can translate to practical uses and solving real-world problems. In your introduction, explain why the topic is important.
Generally, we have found that the best contributions to the Cookbook are **useful**, **novel** or **creative**, or a combination of these.
**Novel or common:** Showcases new developments or techniques. Look out for new research on how to best use LLMs, or new models and capabilities in the API. Alternatively, you can identify common challenges. If you're doing something often, chances are others are too, and having reusable examples to reference can be very helpful.
- **Useful:** Involves concepts or techniques that can be applied broadly and often, and can translate to practical use-cases and solving real-world problems. If you're doing something often, chances are others are too, and having reusable examples to reference can be very helpful.
- **Novel:** Showcases new developments or techniques. Look out for new research on how to best use LLMs, or new models and capabilities in the API.
- **Creative:** Uses LLMs in creative and innovative ways, or combines multiple APIs and tools in novel ways.
**Creative:** Uses LLMs in creative and innovative ways, or combines multiple APIs and tools in novel ways.
Additionally, we strive to maintain a **neutral** tone, and aim for **high quality** writing.
**Neutral:** Maintains a neutral stance on tools and products. While it's natural to have preferences for particular tools, a good guide avoids over-evangelizing or marketing specific products, ensuring integrity and inclusivity.
**High quality:** Well structured, clear and complete. Writing good content ensures others can fully benefit from it. See the rubric below for more details on how we assess the quality of submissions to the Cookbook.
- **Neutral:** Maintains a neutral stance on tools and products. While it's natural to have preferences for particular tools, a good guide avoids over-evangelizing or marketing specific products, ensuring integrity and inclusivity.
- **High quality:** Well structured, clear and complete. Writing good content ensures others can fully benefit from it. See the rubric below for more details on how we assess the quality of submissions to the Cookbook.
## Rubric
@ -26,7 +27,7 @@ For additional advice on writing good documentation, refer to [What Makes Docume
| Relevance | Not relevant to AI or OpenAI API. | Tangentially relevant. | Relevant but not very useful. | Relevant and useful. |
| Uniqueness | Many similar guides/examples. | Some unique aspects, but significant overlap. | Unique with minor overlaps. | Completely unique with fresh insights. |
| Clarity | Confusing and unclear. | Some sections unclear. | Clear language, unclear structure. | Clear language and structure. |
| Correctness | Many errors, code doesn't execute. | Few errors and warnings. | Code works, minor improvements needed. | Completely error free. |
| Completeness | Missing significant portions. | Lacks some explanations. | Mostly complete, minor additions needed. | Complete and detailed. |
| Grammar | Numerous spelling/grammatical errors. | Some spelling/grammatical errors. | Correct grammar, few typos. | Perfect grammar. |
| Relevance | Relevant and useful. | Relevant but not very useful. | Tangentially relevant. | Not relevant. |
| Uniqueness | Completely unique with fresh insights. | Unique with minor overlaps. | Some unique aspects, but significant overlap. | Many similar guides/examples. |
| Clarity | Clear language and structure. | Clear language, unclear structure. | Some sections unclear. | Confusing and unclear. |
| Correctness | Completely error free. | Code works, minor improvements needed. | Few errors and warnings. | Many errors, code doesn't execute. |
| Completeness | Complete and detailed. | Mostly complete, minor additions needed. | Lacks some explanations. | Missing significant portions. |
| Grammar | Perfect grammar. | Correct grammar, few typos. | Some spelling/grammatical errors. | Numerous spelling/grammatical errors. |
simonpfish
8 months ago