docs: improve clarity and consistency across documentation #1606

jxnl · 2025-06-13T17:46:51Z

Summary

This PR improves the clarity and consistency of the documentation by modernizing the messaging and examples throughout key documentation files.

Changes

Updated Files

docs/why.md - Focused on concrete benefits and real-world use cases
docs/concepts/philosophy.md - Emphasized simplicity and developer experience
README.md - Clear value proposition using the modern API
docs/index.md - Effective entry point with unified provider interface

Key Improvements

✨ Uses the modern API throughout all examples
📊 Updated download metrics (3M+ monthly downloads)
🎯 More practical, copy-paste ready code examples
🚀 Clearer value proposition for new users
🔧 Removed outdated provider-specific initialization examples
📝 Consistent messaging across all documentation

Why These Changes?

The documentation was using older patterns and didn't showcase the simplicity of the modern API. These updates make it much clearer why developers should choose Instructor and how easy it is to get started.

Test Plan

All markdown files pass linting
Code examples are syntactically correct
Links are properly formatted
Consistent tone and messaging throughout

Important

Improves documentation clarity and consistency by updating key files with modern examples and messaging, emphasizing Instructor's simplicity and flexibility for structured LLM outputs.

Documentation Updates:
- docs/why.md: Emphasizes the fragmentation problem with LLM providers and how Instructor solves it with a unified API.
- docs/concepts/philosophy.md: Highlights the principles of simplicity, flexibility, and transparency in Instructor's design.
- README.md: Provides a clear value proposition and practical examples using the modern API.
Key Improvements:
- Uses modern API in all examples.
- Updates download metrics to 3M+ monthly downloads.
- Provides practical, copy-paste ready code examples.
- Removes outdated provider-specific initialization examples.
- Ensures consistent messaging across all documentation.

^{This description was created by}^{for 7e7fc05. You can customize this summary. It will automatically update as commits are pushed.}

- Rewrite why.md to focus on concrete benefits and real-world use cases - Update philosophy.md to emphasize simplicity and developer experience - Modernize README.md with clear value proposition using from_provider API - Refresh docs/index.md as effective entry point with unified provider interface - Remove outdated provider-specific examples in favor of from_provider - Add consistent messaging about 3M+ downloads and Pydantic foundation - Improve code examples to be more practical and copy-paste ready This update makes the documentation more approachable for new users while maintaining technical accuracy for experienced developers.

cloudflare-workers-and-pages · 2025-06-13T17:48:30Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	instructor	`9049fc8`	Commit Preview URL	Jun 13 2025, 06:16 PM

ellipsis-dev

Caution

Changes requested ❌

Reviewed everything up to 6ed58da in 2 minutes and 12 seconds. Click for details.

Reviewed 2543 lines of code in 4 files
Skipped 0 files when reviewing.
Skipped posting 4 draft comments. View those below.
Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. README.md:110

Draft comment:
The 'Automatic validation with retries' snippet uses 'client' without showing its initialization. Consider adding a client initialization line (e.g., 'client = instructor.from_provider("openai/gpt-4o-mini")') for clarity.
Reason this comment was not posted:
Confidence changes required: 80% <= threshold 85% None

2. docs/concepts/philosophy.md:56

Draft comment:
Using 'completion._raw_response' accesses a potentially private attribute. Consider adding a note that this is intended for debugging and may change in future releases.
Reason this comment was not posted:
Confidence changes required: 85% <= threshold 85% None

3. docs/index.md:126

Draft comment:
The 'Stream partial results' snippet uses 'client' without re-initialization. Consider including a client initialization to make the example fully self-contained.
Reason this comment was not posted:
Confidence changes required: 80% <= threshold 85% None

4. docs/why.md:115

Draft comment:
The 'Works with Any Provider' snippet uses 'Anthropic()' and 'genai.GenerativeModel()' without importing these. Consider adding the necessary import statements for clarity.
Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 85% This is a documentation example showing how to use different providers. Missing imports could confuse readers trying to follow along. However, this is a very basic issue that most Python developers would understand - they know they need to import classes they use. The example is meant to be illustrative rather than a complete copy-paste solution. The comment identifies a real issue that could make the documentation less clear for beginners. Missing imports are a common source of confusion. While true, this is an extremely basic issue that doesn't warrant a PR comment. The example is clearly illustrative and any Python developer would know to import the classes they use. This comment should be deleted as it points out something too obvious and not important enough to warrant a PR comment.

Workflow ID: wflow_QLwH4WQsstoMuq79

^{You can customize}^{by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

ellipsis-dev · 2025-06-13T17:49:07Z

README.md


 ```python
-import openai
+from typing import List


Consider adding an import for BaseModel (e.g. from pydantic import BaseModel) in the 'Streaming complex objects' snippet to ensure the code is self-contained.

jxnl · 2025-06-13T17:51:43Z

docs/concepts/philosophy.md


-Begin with a function and a return type hint – simplicity is key. With my experience maintaining a large enterprise framework at my previous job over many years I've learned that the goal of making a useful framework is minimizing regret, both for the author and hopefully for the user.
+# Access raw responses
+completion = client.chat.completions.create(


use create_with_completion

jxnl · 2025-06-13T17:51:58Z

docs/concepts/philosophy.md

+
+```python
+# With Instructor
+client = instructor.from_openai(OpenAI())


use from_provider

ellipsis-dev

Important

Looks good to me! 👍

Reviewed 596261e in 49 seconds. Click for details.

Reviewed 24 lines of code in 1 files
Skipped 0 files when reviewing.
Skipped posting 1 draft comments. View those below.
Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. README.md:160

Draft comment:
The new 'Available in Multiple Languages' section is a clear addition. Consider checking for any unintended trailing whitespace in the bullet lines (e.g., lines 165 and 168) for consistency.
Reason this comment was not posted:
Confidence changes required: 33% <= threshold 85% None

Workflow ID: wflow_mogMapbvjdwXumLw

^{You can customize}^{by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

- Update why.md to use from_provider instead of from_openai - Update philosophy.md to use from_provider instead of from_openai - Fix code examples to be complete and runnable - Ensure consistent API usage throughout all documentation

ellipsis-dev

Important

Looks good to me! 👍

Reviewed df6d11d in 1 minute and 38 seconds. Click for details.

Reviewed 110 lines of code in 2 files
Skipped 0 files when reviewing.
Skipped posting 9 draft comments. View those below.
Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. docs/concepts/philosophy.md:29

Draft comment:
Replace from_openai(OpenAI()) with from_provider("openai/gpt-4") for consistency with the unified provider API.
Reason this comment was not posted:
Comment looked like it was already resolved.

2. docs/concepts/philosophy.md:31

Draft comment:
Update inline comment to indicate removing the line returns the raw API, not reverting to OpenAI-specific behavior.
Reason this comment was not posted:
Comment looked like it was already resolved.

3. docs/concepts/philosophy.md:36

Draft comment:
Clarify the non-Instructor example by updating the comment to 'use provider's native client'.
Reason this comment was not posted:
Comment looked like it was already resolved.

4. docs/concepts/philosophy.md:169

Draft comment:
Update process_order to use instructor.from_provider with the vision model; note the removal of the explicit model parameter from the completion call.
Reason this comment was not posted:
Comment did not seem useful. Confidence is useful = 0% <= threshold 85% This comment is purely informative, as it describes a change made in the code without suggesting any improvements or asking for clarification. It doesn't align with the rules for useful comments, which should provide suggestions, ask for specific tests, or confirm intentions when something seems off.

5. docs/why.md:24

Draft comment:
Unify import style by replacing individual provider imports with a single 'import instructor' for a consistent API usage.
Reason this comment was not posted:
Comment looked like it was already resolved.

6. docs/why.md:32

Draft comment:
Change client initialization to instructor.from_provider("openai/gpt-4") to align with the unified provider approach.
Reason this comment was not posted:
Comment looked like it was already resolved.

7. docs/why.md:82

Draft comment:
Update the error-retry example by removing the 'model' parameter and using an explicit message example for clarity.
Reason this comment was not posted:
Comment looked like it was already resolved.

8. docs/why.md:95

Draft comment:
Enhance the streaming example by removing the 'model' parameter and providing a concrete messages example for better copy-paste readiness.
Reason this comment was not posted:
Comment looked like it was already resolved.

9. docs/why.md:112

Draft comment:
Consolidate multi-provider examples under a single unified interface using instructor.from_provider for consistency.
Reason this comment was not posted:
Comment looked like it was already resolved.

Workflow ID: wflow_SkPqXUH2YTpjSjh9

^{You can customize}^{by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

- Rewrite README with compelling value prop and before/after comparison - Transform docs/index.md to start with developer pain points - Revamp why.md to focus on real problems and tangible costs - Redesign philosophy.md with concrete examples over abstract principles - Remove all emojis for professional tone - Use from_provider API consistently throughout - Add real-world examples and use cases - Focus on outcomes and developer experience This update makes the documentation speak directly to developer needs while maintaining technical accuracy and simplicity.

ellipsis-dev

Important

Looks good to me! 👍

Reviewed 8feffbc in 2 minutes and 30 seconds. Click for details.

Reviewed 1561 lines of code in 4 files
Skipped 0 files when reviewing.
Skipped posting 4 draft comments. View those below.
Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. README.md:15

Draft comment:
Provider naming inconsistency: 'openai/gpt-4o-mini' is used here while later examples use 'openai/gpt-4o' or 'openai/gpt-4'. Consider standardizing for clarity.
Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 85% The different model names appear to be intentional: - The simple first example uses gpt-4o-mini, likely as a lighter/cheaper option - The comparison table shows raw OpenAI API which uses gpt-4 - The provider example shows gpt-4o as the main option This variety actually helps show flexibility and options. The inconsistency could potentially confuse readers about which model they should use. Maybe we should standardize. The different model names serve different purposes in different examples. This actually demonstrates the library's flexibility with different models. While there is inconsistency, it appears intentional and beneficial for showing different use cases. The comment should be deleted.

2. docs/concepts/philosophy.md:23

Draft comment:
The use of '[...]' as a placeholder in code examples is clear, but adding a brief note (e.g., ‘placeholder for messages’) would benefit new users.
Reason this comment was not posted:
Confidence changes required: 80% <= threshold 85% None

3. docs/index.md:71

Draft comment:
Again, inconsistent provider identifiers (e.g., 'openai/gpt-4o' vs 'openai/gpt-4') may confuse newcomers. Consider unifying the naming scheme across examples.
Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 85% The inconsistency could be confusing to readers. However, this is documentation, and the exact model name used in examples isn't critical as long as it demonstrates the concept. The comment suggests changing to gpt-4, but we don't actually know which is the correct/intended model name. This feels like a nitpick that doesn't affect functionality. The inconsistency might actually be intentional to show different model variants. Without knowing the actual valid model names for the library, we can't be sure this is even an error. Even if the inconsistency is unintentional, it's a minor documentation issue that doesn't affect code functionality or understanding of the core concepts being taught. This comment should be deleted as it's overly nitpicky about documentation examples and we don't have enough context to know which model name is correct.

4. docs/why.md:7

Draft comment:
The claim '15% of the time it returns garbage' is compelling but may need context or evidence to avoid appearing arbitrary.
Reason this comment was not posted:
Confidence changes required: 80% <= threshold 85% None

Workflow ID: wflow_TG6Em7RTz3URZBM6

^{You can customize}^{by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

jxnl · 2025-06-13T18:06:39Z

@claude make a PR that is just the readme, why, philophy, without changing the index.md

claude · 2025-06-13T18:06:57Z

Claude finished @jxnl's task —— View job

✅ Task Complete: New Branch Created with Subset of Changes

I've successfully created a new commit with just the 3 requested files (excluding docs/index.md):

Commit SHA: 9049fc8862e7e4567e9dc2fd77f993fc97951efa

Files included:

✅ README.md - Streamlined with clear value proposition and modern API examples
✅ docs/why.md - Focuses on practical pain points and real-world benefits
✅ docs/concepts/philosophy.md - Emphasizes simplicity and developer experience

Files excluded (as requested):

❌ docs/index.md - Not included in this commit

Next Steps

The commit is ready, but I need to create the pull request. You can either:

Grant me Bash permissions so I can create the PR using gh pr create
Create the PR manually using the GitHub web interface - you should see a notification about the new commit

The PR should be titled: "docs: improve clarity and impact in key documentation files"

And should mention it's a focused subset of PR #1606 with just the core documentation improvements, excluding index.md as requested.

- Acknowledge that providers now have structured output APIs - Focus on fragmentation and incompatibility between providers - Highlight limitations: no validation, retries, streaming, or complex types - Add badges to docs/index.md for consistency - Include installation options and language availability

This PR improves the clarity and consistency of key documentation files by: - README.md: Streamlined with clear value proposition and modern API examples - docs/why.md: Focuses on practical pain points and real-world benefits - docs/concepts/philosophy.md: Emphasizes simplicity and developer experience Uses the modern from_provider API throughout all examples and provides more practical, copy-paste ready code samples. Co-authored-by: Jason Liu <[email protected]>

ellipsis-dev

Important

Looks good to me! 👍

Reviewed 7cb1d18 in 3 minutes and 3 seconds. Click for details.

Reviewed 509 lines of code in 2 files
Skipped 0 files when reviewing.
Skipped posting 5 draft comments. View those below.
Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. docs/index.md:77

Draft comment:
Inconsistent provider identifier: here it uses 'openai/gpt-4o' while other examples (e.g., in docs/why.md) use 'openai/gpt-4'. Please standardize the provider name for clarity.
Reason this comment was not posted:
Comment was not on a location in the diff, so it can't be submitted as a review comment.

2. docs/why.md:190

Draft comment:
The streaming example uses 'Partial[Recipe]' without defining 'Recipe' or explicitly importing 'Partial'. Consider either defining a sample Recipe model or using an already defined model (e.g., 'User') and show the import for clarity.
Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 80% vs. threshold = 85% The comment identifies a real issue - using an undefined model in documentation can be confusing. The suggestion to use User instead makes sense since it's already defined and used throughout the examples. This would make the documentation more consistent and easier to follow. The missing Partial import is also a valid point. The issue might be minor since readers could infer that Recipe is just an example model. Also, the exact model used isn't critical to demonstrating the streaming concept. While the concept would work with any model, using an undefined model in documentation is poor practice. Consistency and completeness in documentation examples is important for clarity. Keep the comment. The suggested change would improve documentation clarity and consistency by using an already-defined model instead of an undefined one.

3. docs/why.md:62

Draft comment:
The retry logic snippet calls json.loads() without showing an import for the json module. Consider adding 'import json' in the example for completeness.
Reason this comment was not posted:
Confidence changes required: 80% <= threshold 85% None

4. docs/why.md:111

Draft comment:
The shrug emoticon '¯_(ツ)_/¯' may trigger markdown formatting issues due to underscores. Verify that it renders as intended, or consider escaping the underscores.
Reason this comment was not posted:
Confidence changes required: 50% <= threshold 85% None

5. docs/why.md:282

Draft comment:
The 'Get Started →' link references an anchor that should exist. Please verify that the '#start-in-30-seconds' anchor is present in the target file for link consistency.
Reason this comment was not posted:
Confidence changes required: 80% <= threshold 85% None

Workflow ID: wflow_dHUOlfHvv3jI1n7R

^{You can customize}^{by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

github-actions bot added documentation Improvements or additions to documentation enhancement New feature or request size:M This PR changes 30-99 lines, ignoring generated files. labels Jun 13, 2025

ellipsis-dev bot reviewed Jun 13, 2025

View reviewed changes

docs: add other Instructor language implementations to README

596261e

jxnl commented Jun 13, 2025

View reviewed changes

ellipsis-dev bot reviewed Jun 13, 2025

View reviewed changes

jxnl and others added 3 commits June 13, 2025 11:07

docs: revert index.md to main branch version

7e7fc05

jxnl merged commit 1780f35 into main Jun 13, 2025
12 of 14 checks passed

jxnl deleted the feat/improve-docs-clarity branch June 13, 2025 18:11

ellipsis-dev bot reviewed Jun 13, 2025

View reviewed changes

Uh oh!

docs: improve clarity and consistency across documentation #1606

docs: improve clarity and consistency across documentation #1606

Uh oh!

Conversation

jxnl commented Jun 13, 2025 • edited by ellipsis-dev bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Updated Files

Key Improvements

Why These Changes?

Test Plan

Uh oh!

cloudflare-workers-and-pages bot commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

ellipsis-dev bot left a comment

Choose a reason for hiding this comment

Uh oh!

ellipsis-dev bot Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

jxnl Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

jxnl Jun 13, 2025

Choose a reason for hiding this comment

Uh oh!

ellipsis-dev bot left a comment

Choose a reason for hiding this comment

Uh oh!

ellipsis-dev bot left a comment

Choose a reason for hiding this comment

Uh oh!

ellipsis-dev bot left a comment

Choose a reason for hiding this comment

Uh oh!

jxnl commented Jun 13, 2025

Uh oh!

claude bot commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Task Complete: New Branch Created with Subset of Changes

Next Steps

Uh oh!

Uh oh!

ellipsis-dev bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jxnl commented Jun 13, 2025 •

edited by ellipsis-dev bot

Loading

cloudflare-workers-and-pages bot commented Jun 13, 2025 •

edited

Loading

claude bot commented Jun 13, 2025 •

edited

Loading