Documentation Standards
Documentation philosophy
Why document the "why" before the "how"?
Fundamental principle: Documentation must explain why architectural decisions were made, not just how the code works.
Why this principle:
- Informed decisions: The reader can understand the rationale behind the choices
- More efficient debugging: Understanding the "why" helps diagnose problems
- Extensibility: New developers can add features in a consistent way
- Maintainability: Design decisions are documented, not just in the code
What to document
Document:
- Architectural choices: Why the system is structured this way
- Trade-offs: What is sacrificed to obtain certain benefits
- Design decisions: Why one solution is chosen over another
- Assumptions: What the system assumes to function
Do not document (too much):
- Every single function: Too verbose, not very useful
- Obvious logic: If the code is self-documenting, there is no need to explain
- Implementation details: They change often, the rationale less so
Documentation structure
Organizational principles
The navigation is organized by audience; the folders by technical domain.
The site has four tabs, each with its own sidebar (defined in website/sidebars.ts):
| Tab | Reader | Typical pages |
|---|---|---|
| Get started | Newcomers, chat users | getting-started/, user-guide/ |
| API | Developers integrating AION | api-guide/ (hands-on), api-and-runtime/ and security/api-keys.md (reference) |
| Administration | Administrators, operators | admin-guide/, deployment/, configuration/, security/, mcp/, integrations/ |
| Internals | People who develop AION | architecture/, memory/, learning/, benchmarks/, opensource/, standard/ |
docs/
├── index.md # Welcome page (site home)
├── getting-started/ # What is AION, key concepts, quickstart, FAQ
├── user-guide/ # Using the chat app
├── api-guide/ # Task-oriented API guides with code examples
├── admin-guide/ # Administrator checklist
├── api-and-runtime/ # API reference, SSE events, agent pipeline
├── architecture/ # Architecture, observability, design notes
├── clients/ # chat-ui, admin-ui, n8n, SDK
├── configuration/ # Environment, profiles, skills, policies
├── deployment/ # Docker, GHCR, self-update, sandbox
├── integrations/ # MCP overview, WhatsApp, deep research
├── mcp/ # Connectors and the MCP registry
├── memory/ # STM/LTM, Mnemos, compaction, history
├── security/ # Identity, SSO, 2FA, API keys, isolation
├── telegram/ # Telegram channel
└── ... # learning/, benchmarks/, opensource/, standard/
Rules:
- Do not move or rename existing files: source code,
CLAUDE.mdand other pages link to their paths. To move a page to another section, changewebsite/sidebars.ts. - Every page must be in exactly one sidebar. A page missing from
sidebars.tsstill builds but nobody can find it. - Guides vs reference: a guide answers "how do I…?" with steps and runnable examples; a reference lists every field, code and option. Link them both ways instead of mixing them.
- One language: English. UI labels and log strings that only exist in Italian may be quoted, with an English gloss.
Every page starts the same way: frontmatter (title, sidebar_position, description), the H1, then a 2–4 sentence plain-language introduction saying what the feature is, why/when you would use it and who the page is for. Define acronyms on first use. Put the most common task first and developer details (env vars, file paths, internals) after it.
Links:
- Between pages: relative
.mdpaths (../security/api-keys.md#scopes). Broken links fail the build. - To source files: relative paths such as
../../src/api/main.pyorsrc/api/main.py; the build turns them into GitHub links (website/src/remark/repo-links.ts). - When you rename a heading that other pages link to, keep the old anchor:
## New title {#old-anchor}. - Use Docusaurus admonitions (
:::note,:::tip,:::warning,:::danger), not GitHub> [!NOTE]. In prose, wrap<placeholder>and{braces}in backticks (pages are MDX).
Build and preview: cd website && pnpm start (live preview) or pnpm run build (same build as Vercel and Docker; it fails on broken links).
Naming conventions
File name:
- Kebab-case:
agent-pipeline.md,chat-history-and-fts.md - Descriptive:
context-compression.mdnotcompression.md - Technical English:
prometheus-integration.md, notintegrazione-prometheus.md
File structure:
# Frontmatter required
---
sidebar_position: 1
title: Short title for sidebar
description: One-line description
---
# Full title of the document
Content...
Why frontmatter:
- Consistency: All documents have a similar structure
- SEO:
titleanddescriptionfor search - Navigation:
sidebar_positionorders the sidebar
Effective writing
Principles of writing
1. Explain the "why" before the "how"
Incorrect (only "how"):
## Context compression
Compression is handled by `ContextCompressor` in `src/memory/context_compressor.py`.
The `should_compress` function checks if the context exceeds the threshold. If yes, it calls `compress()`.
Correct (first "why"):
## Context compression
**Why compression?** LLM models have token limits (typically 32k).
If the context exceeds the limit, responses are truncated.
**How it works:** Compression keeps the last N messages intact and summarizes
the initial part, reducing token usage while maintaining key information.
**Configuration:** `AION_CONTEXT_COMPRESS_THRESHOLD=0.5` means "compress when
you use 50% of the token budget".
2. Use diagrams to show flows
Example:
Why diagrams:
- Visual understanding: Easier to understand a complex flow
- Reference: The diagram remains stable while code changes
- Quick overview: See the big picture without reading everything
3. Tables for comparisons
Example:
| Feature | Pro | Con | When to use |
|---------|-----|-----|-------------|
| Compression | Reduces tokens | Loses information | Long sessions |
| No compression | Maximum quality | More tokens | Short sessions |
Why tables:
- Clear comparison: They see pros/cons at a glance
- Decision making: They help choose the right option
- Reference: Quick lookup for trade-offs
4. Concrete examples
Example:
**Configuration example:**
```yaml
# config/mcp_registry.yaml
prometheus:
command: python
args:
- mcp_servers/prometheus/server.py
env: {}
Why examples:
- Concrete: Understand how to apply the theory
- Testing: They can verify that it works
- Reference: Template for similar configurations
---
## Quality checklist
### Before publishing, verify:
- [ ] **Explanation of the "why"**: Is the rationale clear?
- [ ] **Trade-offs mentioned**: What is sacrificed to obtain benefits?
- [ ] **When to use**: Are specific situations documented?
- [ ] **Examples**: Are there concrete examples?
- [ ] **Diagrams**: Do diagrams help understand the flow?
- [ ] **Cross-references**: Links to related documents?
- [ ] **Troubleshooting**: Common problems and solutions?
- [ ] **Best practices**: Suggestions for deployment?
### Before modifying an existing document:
- [ ] **Complete reading**: Understand the context before modifying
- [ ] **Consistency**: Maintain style with other documents
- [ ] **Cross-check**: Verify that information does not change between documents
- [ ] **Update links**: Update links if a file is moved/renamed
---
## Document template
```markdown
---
sidebar_position: X
title: Short title for sidebar
description: One-line description
---
# Full title
## Philosophy / Why this exists
**Brief explanation** of why this component exists, what problem it solves.
## Architecture / How it works
**Explanation** of how it works, with:
- Diagrams if applicable
- Table of components
- Data flow
## Trade-offs
**Table** of pros/cons, when to use/disable.
## Configuration
**Table** of configurable variables with defaults and meaning.
## Examples
**Code or config examples** to demonstrate practical use.
## Troubleshooting
Common **problem** and solution.
## Best practices
**Suggestions** for deployment and optimal use.
## Related documents
- [Link to related doc 1]
- [Link to related doc 2]
Examples of quality documentation
Example 1: Good explanation of the "why"
Before:
## STM Consolidator
The STM consolidator cleans up old messages after N turns.
After:
## STM Consolidator - Why and How
**Why consolidate:** Without consolidation, the STM would grow indefinitely,
increasing token costs and latency. The consolidator keeps only relevant messages.
**How it works:** After N turns (`AION_STM_CONSOLIDATE_EVERY`), the consolidator:
1. Analyzes the last M messages (`AION_STM_PRUNE_KEEP`)
2. Removes obsolete messages
3. Keeps only the most recent messages
**Trade-offs:**
- **Pro:** Reduces token usage, improves performance
- **Con:** Loses context of old conversations
**When to enable:** Always, by default. Disable only for very short sessions (< 10 turns).
Example 2: Good trade-off table
Before:
## Compression settings
```yaml
AION_CONTEXT_COMPRESS_ENABLED: 1
AION_CONTEXT_COMPRESS_THRESHOLD: 0.5
After:
## Compression Settings
| Setting | Default | When to modify | Trade-off |
|---------|---------|-------------------|-----------|
| `AION_CONTEXT_COMPRESS_ENABLED` | `1` | Disable for maximum quality | Enable: more efficient | Disable: more tokens |
| `AION_CONTEXT_COMPRESS_THRESHOLD` | `0.5` | 0.3 = early compression | 0.3 = loss of info | 0.7 = risk of truncation |
Example 3: Good Troubleshooting
Before:
## Errors
If there is an error, check logs.
After:
## Troubleshooting
### "Response truncated"
**Symptom:** `finish_reason=length` in the stream
**Cause:** `AION_CHAT_MAX_TOKENS` too low for context + response
**Solutions:**
1. Increase `AION_CHAT_MAX_TOKENS` (e.g. 8192 → 16384)
2. Enable compression: `AION_CONTEXT_COMPRESS_ENABLED=1`
3. Reduce STM: `AION_STM_MAX_TURNS=8`
### "Timeout after 600s"
**Symptom:** `Timeout: too many steps or response too long`
**Cause:** Query too complex or tool execution blocked
**Solutions:**
1. Increase `AION_AGENT_TURN_TIMEOUT`
2. Reduce number of tool calls
3. Verify that the LLM server is reachable
Language and tone
Language
Technical Italian, with English terms for:
- API names:
/chat,/profiles,/admin - Tech terms:
WebSocket,JSON,SQLite,MCP - Library names:
FastAPI,Haystack,Next.js
Tone
Professional, concise, informative:
- Avoid colloquialisms
- Be direct, not verbose
- Use "you" or impersonal form ("the system" not "we do")
Example:
# Incorrect (too colloquial)
"We all agree that this is important"
# Correct (professional)
"This feature is critical for the functioning of the system"
Review and maintenance
When to update the documentation
Update documentation when:
- A significant architecture change occurs
- A new important feature is added
- A significant behavior change occurs
- An error or inaccurate information is found
Do not update for:
- Refactoring that does not change behavior
- Variable name changes without a change in meaning
- Adding comments in code
Review process
Before merge:
- Read the updated documentation
- Verify that it explains the "why"
- Check cross-references
- Verify examples and diagrams
Who does the review:
- Author: Author of the document or code
- Reviewer: Another developer (non-author)
- Approver: Project maintainer (for significant changes)
Useful resources
See Also
- What is AION - Product overview
- Architecture overview - End-to-end flow
- Configuration environment - Configurations
- API documentation - API reference