Simplify learning docs for new users #1479
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add clearer visual diagrams with ASCII art - Simplify code examples and explanations - Create a more logical learning progression - Improve consistency across all learning docs - Make documentation more accessible to beginners 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
Deploying instructor-py with
|
| Latest commit: |
4dae216
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://a9f38bd2.instructor-py.pages.dev |
| Branch Preview URL: | https://docs-simplify-learning-conte.instructor-py.pages.dev |
There was a problem hiding this comment.
👍 Looks good to me! Reviewed everything up to a9591bd in 1 minute and 41 seconds
More details
- Looked at
3350lines of code in19files - Skipped
0files when reviewing. - Skipped posting
15drafted comments based on config settings.
1. mkdocs.yml:252
- Draft comment:
Consider deduplicating integration entries. For example, AWS Bedrock, Azure OpenAI, and Fireworks appear multiple times. Consolidating these will improve maintainability. - Reason this comment was not posted:
Confidence changes required:80%<= threshold85%
None
2. docs/learning/validation/retry_mechanisms.md:120
- Draft comment:
The progressive validation example is clear. Consider adding a brief comment explaining the benefit of the two-step extraction approach to guide users. - Reason this comment was not posted:
Confidence changes required:30%<= threshold85%
None
3. docs/learning/patterns/nested_structure.md:255
- Draft comment:
Consider adding a brief comment explaining why Comment.model_rebuild() is necessary for enabling recursive structures. This will help new users understand its purpose. - Reason this comment was not posted:
Confidence changes required:80%<= threshold85%
None
4. docs/learning/validation/retry_mechanisms.md:120
- Draft comment:
Consider adding a note on potential token consumption and performance impact when max_retries is set, so users are aware that each retry uses additional tokens and time. - Reason this comment was not posted:
Confidence changes required:70%<= threshold85%
None
5. mkdocs.yml:244
- Draft comment:
Duplicate integration entries detected (e.g. AWS Bedrock, Fireworks, Gemini). Consider deduplicating these to avoid navigation clutter and ensure consistency. - 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.
6. docs/learning/patterns/optional_fields.md:117
- Draft comment:
It might be beneficial to add a brief explanation of the 'Maybe' type usage (e.g., its properties like .is_uncertain) to help users understand when and how to use it. - Reason this comment was not posted:
Confidence changes required:60%<= threshold85%
None
7. docs/learning/validation/field_level_validation.md:89
- Draft comment:
Consider adding a comment that clarifies model-level validators (with mode='after') run after individual field validators. This can help explain the validation order to users. - Reason this comment was not posted:
Confidence changes required:60%<= threshold85%
None
8. docs/learning/getting_started/installation.md:134
- Draft comment:
The file is missing a newline at the end. It's a minor style issue, but adding a trailing newline improves consistency and avoids warnings in some editors. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =80%<= threshold85%
The comment is about a minor style issue regarding a missing newline at the end of a file. While this is a style issue, it does not violate any of the rules provided. It is not purely informative as it suggests an improvement for consistency and to avoid warnings in editors. Therefore, it is a valid comment.
9. docs/learning/patterns/list_extraction.md:300
- Draft comment:
The file is missing a trailing newline at the end. While this is a minor formatting detail, many linters expect a newline at the end of files. Please add a newline at the end of the file. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =30%<= threshold85%
The comment is about adding a trailing newline at the end of a file. This is a common practice to ensure compatibility with various tools and systems that expect files to end with a newline. However, it doesn't fall under the specific rules provided, and it's not a critical issue. It doesn't violate any rules, but it's not particularly useful either.
10. docs/learning/patterns/simple_object.md:133
- Draft comment:
It looks like there's no newline at the end of the file. Please add a newline at the end to meet common formatting standards. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =80%<= threshold85%
The comment is about adding a newline at the end of the file, which is a common formatting standard. However, it doesn't violate any of the rules provided. It's a specific suggestion to improve code formatting, which is generally considered good practice.
11. docs/learning/patterns/simple_object.md:38
- Draft comment:
The ASCII diagram in the example (particularly around the 'occupation: str' label) appears misaligned, which may lead to readability issues. Please review and adjust the spacing so that the columns align consistently.
8000
- Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 85%
The rules state "Do NOT comment on pure frontend UI or styling changes". While this is documentation rather than UI, it's still primarily a visual/formatting issue. The diagram is still perfectly readable and conveys its meaning despite the minor misalignment. The comment doesn't point out any functional issues or suggest important code improvements.
The diagram's misalignment could potentially confuse readers about the structure being represented. Documentation readability is important for developer experience.
While documentation quality matters, this is an extremely minor formatting issue that doesn't impact the understanding of the concept being taught. The meaning is still clear despite the small visual imperfection.
This comment should be deleted as it addresses a minor visual formatting issue that doesn't impact the functionality or understanding of the documentation.
12. docs/learning/validation/custom_validators.md:75
- Draft comment:
It looks like the link text 'Validators' might contain a typo ('reask'). Please double-check if it should be updated to the correct path or term. - 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%
Since this is a new documentation file, having correct links is important for user navigation. The fact that the correct path "/concepts/validation.md" exists elsewhere in the document (line 157) strongly suggests that "reask_validation.md" is indeed incorrect. The suggestion appears to be accurate and actionable.
I could be wrong about whether reask_validation.md is actually a valid path - I don't have access to the full repository structure. There could be both files.
While true, the presence of the simpler "validation.md" path elsewhere in the same document, and the fact that "reask" seems out of place, makes this a reasonable correction to suggest.
Keep the comment as it identifies a likely documentation issue that would affect user experience, and provides a clear fix.
13. mkdocs.yml:288
- Draft comment:
Typo detected: The file 'prompting/zero_shot/simtom.md' likely contains a typographical error ('simtom') and should be corrected to the intended filename (e.g., 'simulate.md' or the correct version). - 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.
14. mkdocs.yml:211
- Draft comment:
Minor formatting issue: The 'Multimodal' entry has an extra space before the colon ('Multimodal :'). For consistency, please remove the extra space so it matches the other entries. - 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.
15. mkdocs.yml:338
- Draft comment:
Typographical issue: The entry 'Recurs.-of-Thought' appears to include an unintended period. Please verify if this is the correct label or if it should be corrected (perhaps to 'Recursive-of-Thought' or a similar term). - Reason this comment was not posted:
Comment was on unchanged code.
Workflow ID: wflow_83oKEES7ti5SpnWI
You can customize Ellipsis with 👍 / 👎 feedback, review rules, user-specific overrides, quiet mode, and more.
There was a problem hiding this comment.
👍 Looks good to me! Incremental review on b44591b in 1 minute and 44 seconds
More details
- Looked at
98lines of code in1files - Skipped
0files when reviewing. - Skipped posting
6drafted comments based on config settings.
1. mkdocs.yml:160
- Draft comment:
The new 'Integrations' nav section lists many entries more than once (e.g., AWS Bedrock, Azure OpenAI, Fireworks, Gemini, OpenAI, Vertex AI). Consider deduplicating these items to adhere to DRY principles and prevent confusing navigation. - Reason this comment was not posted:
Comment looked like it was already resolved.
2. mkdocs.yml:163
- Draft comment:
The new 'Integrations' section contains duplicate entries (e.g. AWS Bedrock, Azure OpenAI, OpenAI, Gemini, Fireworks, Together, Vertex AI) appearing in multiple categories. Consider consolidating these duplicates to adhere to DRY principles. - Reason this comment was not posted:
Confidence changes required:80%<= threshold85%
None
3. mkdocs.yml:165
- Draft comment:
Inline comments (e.g. '# Major cloud providers') are used for grouping but won’t be visible in the rendered docs. Consider restructuring using nested lists to clearly display subcategories. - Reason this comment was not posted:
Confidence changes required:80%<= threshold85%
None
4. mkdocs.yml:288
- Draft comment:
It appears that 'simtom.md' (referenced as 'Simulate A Perspective') might be a typographical error. Perhaps this should be renamed to something like 'simulate.md' to maintain consistency. - 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.
5. mkdocs.yml:250
- Draft comment:
The navigation entry 'Multimodal : 'concepts/multimodal.md'' has an unnecessary space before the colon. Consider removing the extra space to match standard formatting conventions. - 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.
6. mkdocs.yml:338
- Draft comment:
The entry '- Recurs.-of-Thought: 'prompting/decomposition/recurs_of_thought.md'' contains what appears to be a typographical error with the period after 'Recurs'. You may want to revise it (e.g., to 'Recursion-of-Thought' or 'Recursive-of-Thought') for clarity and consistency. - 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.
Workflow ID: wflow_7HdrAoUGqY2NIDhm
You can customize Ellipsis with 👍 / 👎 feedback, review rules, user-specific overrides, quiet mode, and more.
- Moved CLI Reference and related topics to a new position - Renamed 'Jobs Board (External)' to 'Find Jobs (External)' - Updated 'Prompt Design' to 'Prompt Engineering' for clarity
There was a problem hiding this comment.
👍 Looks good to me! Incremental review on 76de54a in 1 minute and 1 seconds
More details
- Looked at
34lines of code in1files - Skipped
0files when reviewing. - Skipped posting
6drafted comments based on config settings.
1. mkdocs.yml:271
- Draft comment:
Rename and re-order nav sections: 'Prompt Design' is now 'Prompt Engineering'. Verify consistency with other docs. - Reason this comment was not posted:
Confidence changes required:80%<= threshold85%
None
2. mkdocs.yml:338
- Draft comment:
Moved CLI Reference and Jobs section below Prompt Engineering. Confirm the new placement aligns with the logical learning progression. - Reason this comment was not posted:
Confidence changes required:80%<= threshold85%
None
3. mkdocs.yml:271
- Draft comment:
Renamed 'Prompt Design' to 'Prompt Engineering' for clarity. Ensure all internal references are updated accordingly. - Reason this comment was not posted:
Confidence changes required:0%<= threshold85%
None
4. mkdocs.yml:331
- Draft comment:
Reordering: Moved CLI Reference and Jobs Board (renamed as 'Find Jobs (External)') sections to a later part of the nav. Verify links and cross-references remain valid. - Reason this comment was not posted:
Confidence changes required:0%<= threshold85%
None
5. mkdocs.yml:281
- Draft comment:
Typo detected: The file reference 'prompting/zero_shot/simtom.md' under 'Simulate A Perspective' appears to contain a typo. Please verify if 'simtom.md' is the correct file name or if it should be updated to 'simulate.md' or another intended name. - 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.
6. mkdocs.yml:292
- Draft comment:
Potential phrasing improvement: The label 'Consistent Based Examples' under the 'Few-Shot' section might be improved for clarity. Consider updating it to 'Consistency-Based Examples' if that conveys the intended meaning. - 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.
Workflow ID: wflow_onz7ATCXGH8KOEp8
You can customize Ellipsis with 👍 / 👎 feedback, review rules, user-specific overrides, quiet mode, and more.
There was a problem hiding this comment.
👍 Looks good to me! Incremental review on 4dae216 in 42 seconds
More details
- Looked at
44lines of code in1files - Skipped
0files when reviewing. - Skipped posting
7drafted comments based on config settings.
1. docs/index.md:12
- Draft comment:
Citation block was moved from the top to after the integrations section. This repositioning seems intentional to emphasize the content progression. - Reason this comment was not posted:
Confidence changes required:0%<= threshold85%
None
2. docs/index.md:480
- Draft comment:
Citation block added here aligns with the learning progression. Content is consistent. - Reason this comment was not posted:
Confidence changes required:0%<= threshold85%
None
3. docs/index.md:12
- Draft comment:
Citation block removed from the header. Ensure that moving it improves clarity for new users and doesn't hide important citation info. - Reason this comment was not posted:
Confidence changes required:0%<= threshold85%
None
4. docs/index.md:468
- Draft comment:
Citation block reinserted after integrations. Verify that its new placement aligns with the intended learning progression and remains discoverable. - Reason this comment was not post
8000
ed:
Confidence changes required:0%<= threshold85%
None
5. docs/index.md:615
- Draft comment:
Typographical: Consider correcting "wasnt" to "wasn't" for proper punctuation. - 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.
6. docs/index.md:641
- Draft comment:
Typographical: Please change "infered" to "inferred" to use the correct spelling. - 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.
7. docs/index.md:813
- Draft comment:
Typographical: There appears to be an extraneous backtick at the end of the templating string. Consider removing the extra ` if it's unintentional. - 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.
Workflow ID: wflow_FN1Uzsq6CK2DTbIL
You can customize Ellipsis with 👍 / 👎 feedback, review rules, user-specific overrides, quiet mode, and more.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
🤖 Generated with Claude Code
Important
Simplified and improved learning documentation for new users with visual aids, refined code examples, and enhanced consistency.
This description was created by
for 4dae216. It will automatically update as commits are pushed.