​

Mintlify Documentation State Analysis

​

Executive Summary

The Solvice platform documentation is strategically focused on the VRP (Vehicle Routing Problem) solver, which has excellent, comprehensive documentation. With FILL, CREATE, CLUST, and TASK solvers being deprecated, the documentation strategy should focus on strengthening VRP documentation and clearly communicating the deprecation status of other solvers.

​

Overall Documentation Health Score: 8.5/10

​

Scoring Breakdown:

• VRP Documentation: 9/10 (Excellent)
• Platform Documentation: 7/10 (Good)
• Deprecation Communication: 6/10 (Needs improvement)
• Migration Guidance: 0/10 (Missing)

​

Detailed Analysis

​

1. Documentation Coverage

​

✅ Well-Documented Areas

VRP API (Vehicle Routing Problem) - PRIMARY PRODUCT

• Completeness: 95%
• Structure: Excellent hierarchical organization
• Content Quality: High-quality examples, clear explanations
• Features Documented: 20+ feature pages covering all aspects
• Examples: 5 real-world use cases
• API Reference: Complete with all endpoints
• Schemas: Fully documented request/response structures
• Recent Improvements: Added job complexity and resumable jobs documentation

Platform Overview

• Completeness: 80%
• Content: Good conceptual coverage
• Missing: Deprecation notices for legacy solvers

​

⚠️ Areas Needing Attention

Deprecation Communication

• Current State: No clear deprecation notices
• Impact: Users may waste time exploring deprecated solvers
• Needed:
  • Deprecation banners on existing docs
  • Clear timeline for sunset
  • Migration guides to VRP

Legacy Solver Documentation (FILL, CREATE, CLUST, TASK)

• Status: Being deprecated
• Current Issues:
  • Still referenced in platform docs
  • OpenAPI specs include deprecated endpoints
  • No migration paths documented
  • Some have partial documentation creating confusion

​

2. Navigation and Discoverability

​

Current Navigation Structure (from docs.json)

├── Guides
│   ├── Platform (6 pages)
│   └── VRP API (30+ pages)
├── API Reference
│   └── VRP API only
└── Changelog
    └── VRP only

​

Strategic Navigation Approach

• Correct Focus: Navigation correctly emphasizes VRP as the primary product
• Clean Structure: No clutter from deprecated solvers
• Missing Elements:
  • Deprecation/migration section
  • SDK guides for VRP
  • Advanced VRP integration examples
  • VRP performance optimization guides

​

3. Content Quality Assessment

​

Strengths

• Consistent Formatting: MDX files follow consistent patterns
• Code Examples: Well-structured with proper syntax highlighting
• Interactive Elements: Good use of tabs, accordions, and cards
• Real-world Examples: VRP examples cover practical use cases
• Focused Content: Clear emphasis on the primary VRP product

​

Weaknesses

• Deprecation Handling: No clear communication about solver deprecation
• Legacy References: Platform docs still mention deprecated solvers
• Missing Visual Aids: Limited diagrams or visual explanations
• No Migration Guides: Users of deprecated solvers lack guidance

​

4. Technical Documentation Gaps

1. Deprecation Management

   • No deprecation notices or timelines
   • OpenAPI specs still include deprecated endpoints
   • Missing migration guides from deprecated solvers to VRP

2. VRP SDK Documentation

   • Mentioned in platform overview
   • No actual usage examples or language-specific guides
   • Critical for VRP adoption

3. VRP Advanced Features

   • Performance optimization strategies
   • Large-scale deployment guidance
   • Integration patterns and best practices

4. Error Handling

   • Not systematically documented for VRP
   • No comprehensive error code reference

5. Rate Limiting and Scaling

   • Basic mention only
   • No guidance for high-volume VRP usage

​

5. Content Organization Analysis

​

File Structure Strengths

• VRP: Excellently organized with concepts, features, examples, schemas
• Platform: Good organization but needs deprecation updates
• Clean separation of concerns within VRP documentation

​

Missing Critical Sections

• Deprecation notices and sunset timeline
• Migration guides from deprecated solvers to VRP
• VRP performance optimization deep-dives
• VRP troubleshooting guides
• API versioning and backward compatibility policies

​

6. Deprecation Strategy Recommendations

​

Documentation Approach for Deprecated Solvers

Phase 1: Immediate (Week 1)

• Add deprecation banner component to all FILL, CREATE, CLUST, TASK pages
• Update platform overview to clearly indicate VRP as the primary solution
• Create a deprecation announcement page with timeline

Phase 2: Migration Support (Weeks 2-4)

• Create migration guides:
  • FILL → VRP (shift scheduling via time windows)
  • CREATE → VRP (route planning with constraints)
  • CLUST → VRP (region-based routing)
  • TASK → VRP (job sequencing with relations)
• Document feature mapping between deprecated and VRP APIs
• Provide code migration examples

Phase 3: Cleanup (After sunset date)

• Archive deprecated documentation
• Remove from OpenAPI specs
• Redirect old URLs to migration guides

​

Recent VRP Improvements

Based on recent commits and the audit fix:

• Fixed typos and incorrect field names
• Added missing schema fields
• Created new feature documentation (job complexity, resumable jobs)
• Updated constraint documentation
• Fixed example code accuracy
• Enhanced break management documentation

​

7. Recommendations

​

Immediate Actions (High Priority)

1. Add Deprecation Notices: Clear banners on all deprecated solver docs
2. Update Platform Docs: Remove or mark deprecated solver references
3. Create Migration Guide: Help users move from deprecated solvers to VRP
4. Clean OpenAPI Spec: Remove or mark deprecated endpoints

​

Short-term Improvements (Medium Priority)

1. Enhance VRP Documentation:
   • Add performance optimization guide
   • Create troubleshooting section
   • Document scaling strategies
2. Develop VRP SDK Docs: Language-specific guides and examples
3. Add Success Stories: VRP implementation case studies
4. Create VRP Best Practices: Comprehensive guide for optimal usage

​

Long-term Enhancements (Low Priority)

1. Advanced VRP Guides: Complex routing scenarios and solutions
2. Interactive VRP Tutorials: Step-by-step guided experiences
3. VRP Video Content: Embedded tutorials or explanations
4. VRP Playground: Interactive API testing environment
5. Community Examples: User-contributed VRP solutions

​

8. Documentation Metrics

​

9. User Impact Analysis

​

Current State Impact:

• New Users: Correctly focused on VRP (positive)
• Legacy Users: May be confused by deprecated solver references
• Migration Users: Lack guidance to move to VRP
• Enterprise Customers: Need clearer product roadmap communication

​

Potential After Improvements:

• Clarity: Clear understanding of Solvice’s VRP focus
• Migration Success: Smooth transition for legacy users
• VRP Adoption: Increased usage through better documentation
• Support Efficiency: Fewer questions about deprecated features
• Developer Confidence: Clear product direction and stability

​

10. Conclusion

The Mintlify documentation for Solvice is well-positioned with excellent VRP documentation as the primary product. With the strategic decision to deprecate FILL, CREATE, CLUST, and TASK solvers, the documentation strategy should pivot from expanding coverage to:

1. Communicating Deprecation: Clear notices and timelines
2. Facilitating Migration: Comprehensive guides for moving to VRP
3. Strengthening VRP: Even deeper documentation for the core product
4. Cleaning Legacy: Remove confusion from deprecated references

Priority Action: Add deprecation notices and create migration guides to help users transition to VRP. This maintains the high score of 8.5/10 while improving user experience.

Long-term Goal: Position Solvice documentation as the gold standard for VRP solutions, with comprehensive guides, examples, and tools that make VRP implementation straightforward for any use case.