[Design Proposal] Documentation Site for Agent Manager

[AnoshanJ]

Problem

The platform needs a scalable documentation portal. Current docs are fragmented across READMEs, leading to:

• Poor Discoverability: Difficult for users to navigate the agent management platform codebase, understand architecture and concepts.
• Versioning Challenges: Documentation is tightly coupled to the main branch and lacks versioning, making it difficult to track changes across releases or maintain accurate docs for multiple platform versions.
• AI-Readiness Gap: No structured format for LLM indexing or semantic search.
• High Friction: Inconsistent workflows for contributors and high maintenance overhead. This can be a barrier to get started quickly.

Current State (2/2/2026):
The documentation site has been implemented using Docusaurus, with an initial release (https://wso2.github.io/agent-manager/). LLM readiness (llms.txt), algolia search integration, copy as markdown/ai chat options are functional and complete.

User Stories

• As an Agent Developer/Platform Administrator:, I want clear and searchable documentation so that I can quickly understand how to configure and use the platform and manage AI agents.
• As a contributor, I want a simple and consistent documentation workflow so that I can easily add or update content.
• As a documentation maintainer, I want a system that scales with the project and minimizes long-term maintenance cost.
• As an AI consumer (LLM / agent), I want structured, machine-readable documentation so that the documentation can be indexed and reasoned about effectively.

Existing Solutions

• Docusaurus

  • Widely used open-source documentation framework.

  • Docs-as-code model with Markdown/MDX and React customization.

  • Strong community support and extensibility.

  • Free but Requires self-hosting and manual integration for advanced features (e.g., AI readiness).

• Mintlify

  • Paid and Hosted, documentation platform with an AI-first approach.

  • Built-in support for API documentation, semantic search, and AI assistants.

  • Automatically provides LLM-friendly formats (e.g., llms.txt).

  • Less control at the infrastructure level and introduces vendor dependency.

• Current workaround

  • Documentation is fragmented across README files and repositories.

  • No single authoritative documentation portal for the platform.

Proposed Solution

Based on the evaluation conducted (See older version of document), we have decided to proceed with Docusaurus as the documentation framework for the platform.

Docusaurus provides a scalable, docs-as-code approach that aligns well with our Git-based development workflow and long-term maintenance goals.

Key reasons for this decision:

• Docs-as-Code: Native support for Markdown/MDX with Git-based contribution workflows.
• Versioning Support: Built-in documentation versioning aligned with platform and Helm chart releases.
• Cost & Ownership: Open-source with no licensing cost and no vendor lock-in.

The Docusaurus-based documentation site has been successfully implemented, and Version 1 (V1) of the documentation was released on 30/01/2026. This includes the core documentation structure and initial content.

Next Steps:

• Add LLM-friendly artifacts (e.g., llms.txt) to improve AI indexing
• Enable search and AI-assisted documentation capabilities
• Restructure documentation with improved information architecture
• Improve documentation depth, clarity, and overall content quality

Alternatives Considered

No response

Open Questions

No response

Milestones

Phase	Scope	Description	Status
1	Requirements Definition & Comparative Analysis	Define documentation requirements. Perform a structured comparison of Docusaurus and Mintlify, including AI-readiness, contributor workflow, and long-term sustainability.	✅ Completed (28/01/2026)
2	Documentation Site Setup	Set up documentation site using Docusaurus. Validate hosting, navigation, and base configuration.	✅ Completed (29/01/2026)
3	Documentation Site – V1	Build and publish the initial V1 documentation site with core sections.	✅ Completed (30/01/2026)
4	AI & Search Enablement	Add llms.txt, enable search, and introduce AI-assisted documentation capabilities.	Partially Complete
5	Documentation Quality & Restructuring	Improve documentation structure, consistency, depth, and overall content quality targeting the various user personas.	Planned
6	Documentation Automation	Automate documentation generation and updates as part of platform and release workflows (e.g., versioned docs updates on releases).	Planned

[a5anka]

@AnoshanJ Shall we update the document with the decision to proceed with the docusaurus and details on the implementation?

[AnoshanJ]

Updated with decision to proceed with docusaurus

[AnoshanJ]

Design Proposal updated on 02/02/2026

[AnoshanJ]

Design Proposal updated on 13/02/2026