Skip to content

DOCUMENTATION_STYLE_GUIDE.md

Latest commit

 

History

History
232 lines (168 loc) · 5.27 KB

DOCUMENTATION_STYLE_GUIDE.md

File metadata and controls

232 lines (168 loc) · 5.27 KB

Agentic Brain Documentation Style Guide

Version: 1.0 Date: 2026-04-08 Authority: Based on Chicago Manual of Style, Microsoft Writing Style Guide

Document Purpose

This style guide ensures consistent, professional typography across all Agentic Brain documentation suitable for print publication, web display, and accessibility compliance.

Typography Standards

Headings

Use clear, descriptive headings without emoji prefixes:

# Document Title (H1)
## Major Section (H2)
### Subsection (H3)
#### Detail Level (H4)

❌ Avoid:

# 🚀 Quick Start
## 📚 Documentation
### 🔧 Configuration

✅ Preferred:

# Quick Start
## Documentation
### Configuration

Emphasis and Formatting

Element Markdown Use Case Example
Strong **text** Key concepts, UI elements GraphRAG
Emphasis *text* First use of terms, book titles retrieval-augmented generation
Code `text` Code, filenames, commands agentic-brain

Avoid excessive bolding: Limit bold text to truly important concepts.

Punctuation

Dashes

  • Em dash (—): Parenthetical thoughts, abrupt changes

    • Correct: Agentic Brain—the open-source framework—supports multiple LLMs
    • Incorrect: Agentic Brain — the open-source framework — supports multiple LLMs

  • En dash (–): Ranges, compound adjectives

    • Correct: pages 1–10, Chicago–New York flight

  • Hyphen (-): Compound words, line breaks

    • Correct: well-known, state-of-the-art

Quotes

  • Straight quotes in code: "environment variable"
  • Curly quotes in prose: "user-friendly interface"

Numbers and Data

  • Spell out one through nine: three models, five minutes
  • Use numerals for 10+: 15 agents, 100+ loaders
  • Thousands separator: 10,800 tests (not 10800)
  • Percentages: 45% (no space), 99.2% (consistent decimals)

Markdown Standards

Code Blocks

Always include language identifiers:

```bash
pip install agentic-brain
from agentic_brain import Agent
agent = Agent("assistant")
{
  "name": "agentic-brain",
  "version": "3.1.3"
}

### Lists

Use consistent formatting:

```markdown
- Unordered lists use hyphens (-)
- Maintain parallel structure
- Keep items concise

1. Ordered lists use numbers
2. Include proper spacing
3. Maintain consistent punctuation

Tables

Ensure proper alignment and formatting:

| Feature | Status | Notes |
|---------|--------|-------|
| GraphRAG | ✅ | Production ready |
| Voice I/O | ✅ | 180+ voices |
| TurboSwarm | ✅ | 15+ parallel agents |

Links

Use descriptive link text:

✅ See the [TurboSwarm documentation](./docs/TURBOSWARM.md) for details.
❌ Click [here](./docs/TURBOSWARM.md) for more information.

Terminology Standards

Consistent Terms

✅ Preferred ❌ Avoid
AI agent framework agentic framework, agent framework
GraphRAG Graph RAG, graph RAG
LLM orchestration LLM routing, model routing
open source open-source (as noun)
command line command-line (as noun)

Capitalization

  • Product names: Agentic Brain, TurboSwarm, Neo4j
  • Technologies: GraphRAG, RAG, API, SDK, CLI
  • Companies: OpenAI, Anthropic, Google
  • Standards: WCAG 2.1, SOC 2, HIPAA

Accessibility Guidelines

Screen Reader Compatibility

  • Use semantic heading hierarchy (H1 → H2 → H3)
  • Provide alt text for images: ![Architecture diagram](image.png)
  • Use descriptive link text
  • Avoid color-only information

Voice Output Optimization

  • Write scannable content with clear structure
  • Use parallel phrasing in lists
  • Keep sentences concise for audio consumption
  • Include pronunciation guides for technical terms

File-Specific Guidelines

README.md

  • Lead with clear value proposition
  • Use scannable structure with sections
  • Include quick start within first 100 lines
  • Minimize marketing language, focus on facts

CONTRIBUTING.md

  • Use imperative mood for instructions
  • Provide complete examples
  • Include troubleshooting for common issues
  • Maintain friendly but professional tone

API Documentation

  • Use consistent parameter formatting
  • Include complete, runnable examples
  • Document error conditions
  • Provide response schemas

Quality Checklist

Before publishing any documentation:

  • Headings follow semantic hierarchy (no emoji prefixes)
  • Code blocks include language tags
  • Tables are properly aligned
  • Links use descriptive text
  • Terminology matches style guide
  • Em dashes used correctly (—)
  • Numbers formatted consistently
  • Excessive bolding removed
  • Content is scannable and accessible

Tools and Enforcement

Automated Checks

  • markdownlint: Markdown formatting consistency
  • textlint: Prose style and terminology
  • alex: Inclusive language checking

Manual Review

  • Typography consistency
  • Professional tone assessment
  • Accessibility compliance
  • Print suitability verification

Maintained by: Automated Analysis Next Review: 2026-07-08 Change Log: See CHANGELOG.md for style guide updates