diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5e5d504..fcc4a74 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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. diff --git a/registry_schema.json b/project/registry_schema.json similarity index 100% rename from registry_schema.json rename to project/registry_schema.json diff --git a/project/rubric.md b/project/rubric.md new file mode 100644 index 0000000..0b8b716 --- /dev/null +++ b/project/rubric.md @@ -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. | diff --git a/registry.yaml b/registry.yaml index da70878..2f8fb39 100644 --- a/registry.yaml +++ b/registry.yaml @@ -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