docs_todo.md

Documentation Improvement Tasks

1. Create a Better Getting Started Experience

• Create a dedicated "Getting Started" guide with linear learning path
• Build a focused quickstart guide that's more direct than current index.md
• Add a troubleshooting/FAQ section for common issues
• Include environment setup instructions for each provider

2. Standardize Documentation Format

• Add documentation guidelines to CLAUDE.md for future contributors
• Create a template for provider integration pages
• Create a template for concept pages
• Create a template for example/cookbook pages
• Ensure consistent headings and structure across all pages

3. Enhance Content Organization

• Group concepts into logical categories (core, advanced, etc.)
• Consolidate duplicate concept pages (e.g., Union and Unions)
• Create proper Tutorials index page instead of SEO placeholder
• Add clear "what's next" sections to guide through learning path

4. Improve Code Examples

• Ensure all examples include complete import statements
• Add environment setup instructions where needed
• Standardize code formatting and comments across examples
• Include expected output for all examples

5. Add Missing Documentation

• Add documentation for Anyscale provider
• Add documentation for Databricks provider
• Create migration guides from similar libraries
• Add comparison of different modes supported by providers
• Add architectural diagrams explaining how Instructor works

Completed Tasks

1. Added documentation for Anyscale and Databricks providers
2. Created documentation templates for providers, concepts, and cookbooks
3. Added documentation guidelines to CLAUDE.md
4. Created a dedicated Getting Started guide
5. Added a comprehensive FAQ
6. Improved Tutorials index page
7. Updated mkdocs.yml to include new pages
8. Created architecture documentation with Mermaid diagrams
9. Reorganized concepts into logical categories
10. Created a mode comparison guide
11. Added "What to Read Next" sections with recommendations
12. Consolidated duplicate concept pages (Union and Unions)
13. Created migration guides from similar libraries
14. Created a complete feature comparison table
15. Standardized documentation headings and structure
16. Improved code examples with complete imports, setup, formatting, and expected outputs

Priority Order

1. Fix critical issues (missing providers, broken links)
2. Standardize templates and formats
3. Improve getting started experience
4. Enhance content organization
5. Add detailed guides and diagrams

Code Example Standardization

• All examples must include complete import statements (standard lib → third-party → local)
• Environment setup must be shown (API keys, etc.) or referenced
• Use consistent model versions (latest stable for each provider)
• Include error handling where appropriate
• Use proper type annotations
• Add docstrings for complex functions
• Show expected output in consistent format
• Specify mode explicitly when not using defaults
• Include validation checks where helpful
• Follow Black formatting conventions