Documentation Style Guide

How to write PraisonAI documentation pages — structure, components, diagrams, and writing rules

Every PraisonAI documentation page follows the same structure, component set, and visual language — this guide is both the reference and the example.

from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Research and summarise topics clearly.",
)

agent.start("What is agentic AI?")

The user copies the opening example, runs the agent, then follows the page structure below.

Documentation Creation Process

Read the SDK source before writing anything — documentation must reflect SDK ground truth, not assumptions.

1. Read SDK source

   Open and read the actual SDK implementation file in praisonaiagents/ before writing a single word of documentation.

   # Example: reading agent source before documenting
   # praisonaiagents/agent/agent.py  ← read this first
   from praisonaiagents import Agent
   
   agent = Agent(
       name="Research Agent",
       instructions="Research and summarize topics"
   )
   agent.start("What is agentic AI?")

2. Extract all parameters

   Pull every parameter, type, default value, and description from the SDK source or config class.

   # praisonaiagents/config/feature_configs.py
   @dataclass
   class CachingConfig:
       enabled: bool = True          # Extract: enabled, bool, True
       ttl: int = 3600               # Extract: ttl, int, 3600
       backend: str = "memory"       # Extract: backend, str, "memory"

3. Check existing docs

   Search docs/ for related pages before creating a new one — avoid duplication, ensure consistency.

4. Write the page

   Follow the Page Structure Template and every rule in this guide.

SDK-First Cycle

Never batch-update multiple pages without reading source for each.

File Locations

Multi-SDK Reference

praisonai-ts/src/
├── agents/           # Agent implementations
├── tools/            # Tool definitions
├── memory/           # Memory implementations
├── mcp/              # MCP protocol support
├── observability/    # Tracing integrations
└── index.ts          # Main exports

praisonai-rust/praisonai/src/
├── agents/           # Agent implementations and builders
├── llm/              # LLM providers
├── tools/            # Tool system
├── memory/           # Memory stores
├── mcp/              # MCP client
├── parity/           # Parity-shim modules (config, telemetry, plugins, param_resolver)
├── display/          # Display and callbacks
├── planning/         # Planner and PlanStep
├── session/          # Session
├── streaming/        # Streaming metrics
├── sandbox/          # Sandbox config
├── embedding/        # Embedding config
├── error.rs          # Result/error helpers
└── lib.rs            # Main exports

Folder Placement Rules

Where a file lives determines who can change it — AI agents have write access to most folders but never docs/concepts/.

AI Agent Behavioural Rules

Page Structure Template

Every documentation page follows this exact skeleton.

---
title: "Feature Name"
sidebarTitle: "Feature Name"
description: "One-line description of what this feature does"
icon: "icon-name"
---

{/* One sentence explaining the feature — what it does, not how */}

{/* Hero Mermaid diagram showing the concept visually */}

## Quick Start

<Steps>
<Step title="Simple Usage">
{/* Minimal code example — enable with True */}
</Step>

<Step title="With Configuration">
{/* Code example with config class */}
</Step>
</Steps>

---

## How It Works

{/* Sequence diagram or flow diagram */}

{/* Brief explanation table */}

---

## Configuration Options

{/* Link to auto-generated SDK reference — DO NOT duplicate SDK parameters here */}

<Card title="[Feature] API Reference" icon="code" href="/docs/sdk/typescript">
  TypeScript configuration options
</Card>

---

## Common Patterns

{/* 2–3 practical usage patterns */}

---

## Best Practices

<AccordionGroup>
{/* 3–4 best practices as accordions */}
</AccordionGroup>

---

## Related

<CardGroup cols={2}>
{/* 2 related concept pages */}
</CardGroup>

Mermaid Diagram Standards

Every page starts with a hero Mermaid diagram using the standard colour scheme.

Colour Scheme

Diagram Types by Use Case

graph LR
    subgraph "Feature Name"
        A[📋 Input] --> B[🧠 Process]
        B --> C[✅ Output]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class A input
    class B process
    class C output

sequenceDiagram
    participant User
    participant Agent
    participant Feature

    User->>Agent: Request
    Agent->>Feature: Process
    Feature-->>Agent: Result
    Agent-->>User: Response

Mintlify Components Usage

Every page must use `

,

, and

` — these are not optional.

Required Components

Component	Purpose	Required In
`

| Sequential flows | Quick Start section | |

| Grouped content | Best Practices section | |

| Related links | Related section | |

| Multi-language examples | Code comparison | |