mirror of
https://github.com/james-m-jordan/openai-cookbook.git
synced 2025-05-09 19:32:38 +00:00
Add rubric and organize project resources (#782)
This commit is contained in:
Simón Fishman
GitHub
parent
fa7b3b93a1
commit
fc8411231f
41
.github/pull_request_template.md
vendored
41
.github/pull_request_template.md
vendored
@ -2,37 +2,24 @@
|
||||
|
||||
Briefly describe the changes and the goal of this PR. Make sure the PR title summarizes the changes effectively.
|
||||
|
||||
## Changes
|
||||
|
||||
List the major and minor changes.
|
||||
|
||||
- Major Changes
|
||||
- ...
|
||||
- Minor Changes
|
||||
- ...
|
||||
|
||||
## Motivation
|
||||
|
||||
Why are these changes necessary? How do they improve the cookbook?
|
||||
|
||||
## Self Review Checklist
|
||||
---
|
||||
|
||||
- [ ] Is the writing easily skimmable?
|
||||
- Sections have informative titles.
|
||||
- Key takeaways are upfront.
|
||||
- Short paragraphs and topic sentences are used.
|
||||
- [ ] Is the writing quality high?
|
||||
- Sentences are simple and unambiguous.
|
||||
- Demonstrative pronouns are avoided or clearly referenced.
|
||||
- No left-branching sentences.
|
||||
- [ ] Is the content universally helpful?
|
||||
- Terminology is specific and avoids jargon.
|
||||
- Provides solutions to common problems.
|
||||
- Code examples are general and exportable.
|
||||
- [ ] Is the content consistent?
|
||||
- Styling and formatting align with existing documentation.
|
||||
- Consistent use of punctuation and case.
|
||||
## For contributions of new content
|
||||
|
||||
When contributing a new example, make sure to add a new entry for it in [registry.yaml](/registry.yaml) to render it on the cookbook website.
|
||||
When contributing new content, make sure to read through our [contributions rubric](/project/rubric.md) before submitting, and complete the following action items:
|
||||
|
||||
**Note:** For additional guidelines on writing good documentation, check out [What Makes Documentation Good](https://cookbook.openai.com/what_makes_documentation_good).
|
||||
- [ ] 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.
|
||||
- [ ] 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.
|
||||
|
||||
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.
|
||||
|
||||
107
project/rubric.md
Normal file
107
project/rubric.md
Normal file
@ -0,0 +1,107 @@
|
||||
# Rubric
|
||||
|
||||
The OpenAI Cookbook is a community-driven resource aimed at sharing knowledge in a way that is accessible, engaging, and enriching for everyone. To ensure the quality of submissions, we have established a rubric that assesses each contribution on various areas.
|
||||
|
||||
Each area is rated on a scale from 1 to 5, with 1 being the lowest and 5 being the highest. The purpose of this rating system is to maintain a high standard of quality, relevance, and uniqueness in all contributions. Contributions that score lower than a 3 in any of the areas will generally be rejected.
|
||||
|
||||
We encourage contributors to familiarize themselves with this rubric before writing content. Understanding the criteria not only increases the chances of your contribution being accepted, but also helps in creating a resource that is comprehensive, clear, and beneficial for all users.
|
||||
|
||||
For additional guidelines on writing good documentation, refer to [What Makes Documentation Good](https://cookbook.openai.com/what_makes_documentation_good).
|
||||
|
||||
## Template
|
||||
|
||||
| Criteria | Score |
|
||||
| ----------------------------- | ----- |
|
||||
| Relevance | |
|
||||
| Uniqueness | |
|
||||
| Spelling and Grammar | |
|
||||
| Clarity and Comprehensibility | |
|
||||
| Accuracy and Correctness | |
|
||||
| Usability | |
|
||||
| Completeness | |
|
||||
|
||||
## Breakdown
|
||||
|
||||
#### Relevance
|
||||
|
||||
Is the content related to building with the OpenAI API?
|
||||
|
||||
| Score | Description |
|
||||
| ----- | --------------------------------------------------- |
|
||||
| 1 | Misaligned with the audience's needs. |
|
||||
| 2 | Partial alignment but needs work. |
|
||||
| 3 | Moderately aligned with the target audience. |
|
||||
| 4 | Well-aligned, mostly meets audience needs. |
|
||||
| 5 | Perfectly aligned with the audience's expectations. |
|
||||
|
||||
#### Uniqueness
|
||||
|
||||
Does the content offer new insights or unique information compared to existing documentation?
|
||||
|
||||
| Score | Description |
|
||||
| ----- | ------------------------------------------------------ |
|
||||
| 1 | Content largely redundant with existing documentation. |
|
||||
| 2 | Significant overlap, some unique aspects. |
|
||||
| 3 | Moderate uniqueness, balanced content. |
|
||||
| 4 | Mostly unique content, minor overlaps. |
|
||||
| 5 | Completely unique, fresh insights or new information. |
|
||||
|
||||
#### Spelling and Grammar
|
||||
|
||||
Are there spelling or grammatical errors present?
|
||||
|
||||
| Score | Description |
|
||||
| ----- | --------------------------------------------------------------- |
|
||||
| 1 | Numerous spelling and grammatical errors present. |
|
||||
| 2 | Several errors that need correction. |
|
||||
| 3 | Generally well-spelled and grammatically correct, a few errors. |
|
||||
| 4 | Almost entirely free of spelling and grammatical errors. |
|
||||
| 5 | Completely free of spelling and grammatical errors. |
|
||||
|
||||
#### Clarity and Comprehensibility
|
||||
|
||||
Is the language easy to understand? Are things well-explained?
|
||||
|
||||
| Score | Description |
|
||||
| ----- | --------------------------------------------------- |
|
||||
| 1 | Confusing, unclear language. |
|
||||
| 2 | Some clarity, but requires significant improvement. |
|
||||
| 3 | Moderately clear, minor issues. |
|
||||
| 4 | Clear language, minimal confusion. |
|
||||
| 5 | Exceptionally clear and concise. |
|
||||
|
||||
#### Accuracy and Correctness
|
||||
|
||||
Are the facts, code snippets, and examples correct and reliable? Does everything execute correctly? Is the information included up to date?
|
||||
|
||||
| Score | Description |
|
||||
| ----- | -------------------------------------------- |
|
||||
| 1 | Many inaccuracies or misleading information. |
|
||||
| 2 | Some inaccuracies needing correction. |
|
||||
| 3 | Generally accurate, minor mistakes. |
|
||||
| 4 | Highly accurate, slight improvements needed. |
|
||||
| 5 | Completely accurate and thoroughly vetted. |
|
||||
|
||||
#### Usability
|
||||
|
||||
Is the content well organized and easy to navigate? Is the code easy to run?
|
||||
|
||||
| Score | Description |
|
||||
| ----- | ------------------------------------------ |
|
||||
| 1 | Difficult to navigate or use. |
|
||||
| 2 | Usable but needs significant improvements. |
|
||||
| 3 | User-friendly, some navigational issues. |
|
||||
| 4 | Highly usable, well-structured. |
|
||||
| 5 | Extremely user-friendly and intuitive. |
|
||||
|
||||
#### Completeness
|
||||
|
||||
Is the content thorough and detailed? Are there things that weren’t explained fully?
|
||||
|
||||
| Score | Description |
|
||||
| ----- | --------------------------------------- |
|
||||
| 1 | Missing significant content. |
|
||||
| 2 | Lacks some essential information. |
|
||||
| 3 | Mostly complete, minor gaps. |
|
||||
| 4 | Comprehensive, slight additions needed. |
|
||||
| 5 | Fully complete and all-encompassing. |
|
||||
@ -1,4 +1,4 @@
|
||||
# yaml-language-server: $schema=./registry_schema.json
|
||||
# yaml-language-server: $schema=./admin/registry_schema.json
|
||||
|
||||
# This file is used to generate cookbook.openai.com. It specifies which paths we
|
||||
# should build pages for, and indicates metadata such as tags, creation date and
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user