docs: update docs structure and add new docs.json from mintlify

[tonykipkemboi]

• add changelog page,
• fix formatting issues
• replace mint.json with the new format of docs.json

[joaomdmoura]

Disclaimer: This review was made by a crew of AI Agents.

Code Review Comment for PR #2400

Overview

This pull request significantly enhances the documentation for the CrewAI project by adding a well-structured changelog, replacing the outdated mint.json with docs.json for better organization, and addressing various formatting issues across multiple documentation files. These changes demonstrate a thoughtful approach to improving user engagement and clarity in the documentation.

1. docs/changelog.mdx (New File)

The introduction of a changelog is a crucial step towards better project transparency.

Positive Aspects:

• Clear Structure: The use of semantic versioning with distinct categories (Features, Bug Fixes, Documentation) provides clarity.
• Consistent Date Formatting: Enhances the readability of the changelog.

Suggestions for Improvement:

• Link to Relevant PRs: Adding direct links to the associated pull request numbers would enhance traceability and context.
• Detailed Migration Notes: For breaking changes, consider expanding on migration requirements for users.

Example Suggested Format:

<Update label="2024-03-17" description="v0.108.0">
  **Features**
  - Updated `crew.py` template to conform to new formatting ([#2345](link-to-pr)).
  - Improved handling for LLM streaming responses ([#2346](link-to-pr)).
  
  **Breaking Changes**
  - [Migration Required] Changes to Event Listener implementation.
</Update>

2. docs/concepts/llms.mdx

This document provides essential insights into large language models.

Issues and Fixes:

• Unclosed Tab Component: Fixed this issue ensures accurate rendering.
• Indentation Corrections: Improved formatting for better readability.

Fixed Version:

<Tabs>
  <Tab>
    <Tip>
      Use larger context models for extensive tasks
    </Tip>
  </Tab>
</Tabs>

3. docs/docs.json (New File) vs. docs/mint.json (Deleted)

This transition marks a significant improvement in documentation organization.

Positive Changes:

• Enhanced Navigation: The new structure simplifies access to various documentation sections.
• Schema Validation: The addition of a $schema entry improves the reliability of the documentation format.

Suggestions for Enhancement:

• Add Versioning Information: Including document versioning will assist users in tracking updates more easily.
• Optimize SEO Metadata: Enhancing visibility on search engines can increase user engagement.
• Include Rate Limiting Information: Clarity on API usage policies is key for users.

Recommended Additions:

{
  "version": "1.0.0",
  "metadata": {
    "keywords": ["crewai", "ai", "agents"],
    "description": "Official documentation for CrewAI framework"
  },
  "api": {
    "rate_limit": {
      "requests_per_minute": 60
    }
  }
}

4. docs/guides/advanced/customizing-prompts.mdx

Formatting improvements enhance the guidance provided in this file.

Issues Fixed:

• Corrected YAML front matter and ensured proper newline insertion to improve document clarity.

Current Format:

---
title: Customizing Prompts
description: Vital tips for low-level customization...
icon: message-pen
---

General Recommendations:

1. Documentation Versioning and Search: Implement version control and a search index to better guide user navigation.
2. Maintain Markdown Consistency: Enforce a markdown linter to standardize documentation presentation.
3. Regular Quality Checks: Introduce workflows for validation, link checking, and spellchecking to uphold documentation integrity.

Summary of Changes

• Comprehensive changelog added for better change tracking.
• Transition from mint.json to docs.json for improved documentation management.
• Various formatting issues addressed to enhance overall document quality.

These enhancements significantly uplift the quality of the documentation, ensuring it serves as a reliable resource for users while also facilitating future updates and maintenance. Increased diligence regarding linking and version control will further establish robust documentation practices moving forward.