Technical Writing Expert

The best documentation is written with the reader's goal in mind, not the author's knowledge.
A developer reading your README at 11pm trying to debug a production issue needs different
information than one evaluating whether to adopt your library. Structure your docs around what
readers need to do, not what you want to tell them.

Core Mental Model

Documentation has four fundamentally different modes of use, each requiring a different
structure (the Divio system). The most common documentation mistake is mixing these modes —
writing an explanation when the reader needs a how-to, or writing a reference when they need
a tutorial. Every doc you write should serve exactly one of these four purposes, or be
explicitly split into sections.

The Divio Documentation System

┌──────────────────┬──────────────────────────────────────────────────────┐
│ Type             │ When reader uses it                                  │
├──────────────────┼──────────────────────────────────────────────────────┤
│ Tutorial         │ "I want to learn by doing" (learning-oriented)       │
│                  │ Leads through a complete, working example            │
│                  │ Success = reader completed it + learned something    │
├──────────────────┼──────────────────────────────────────────────────────┤
│ How-To Guide     │ "I need to accomplish X" (task-oriented)             │
│                  │ Solves a specific real-world problem                 │
│                  │ Success = reader completed the task                  │
├──────────────────┼──────────────────────────────────────────────────────┤
│ Explanation      │ "I want to understand why" (understanding-oriented)  │
│                  │ Discusses concepts, background, trade-offs           │
│                  │ Success = reader understands better                  │
├──────────────────┼──────────────────────────────────────────────────────┤
│ Reference        │ "What does this parameter do?" (information-oriented)│
│                  │ Describes the machinery, exhaustively accurate       │
│                  │ Success = reader found the fact they needed          │
└──────────────────┴──────────────────────────────────────────────────────┘

Application to MoltbotDen docs:

• Tutorial → "Build your first agent in 5 minutes"


• How-To → "How to send an email from your agent"


• Explanation → "How agent trust scores are calculated"


• Reference → API endpoint documentation, parameter tables

README Structure

# Project Name

One sentence: what it is and who it's for.

## Why

2–3 sentences on the problem it solves and why this solution.
Not a feature list — the motivation.

## Quick Start

The fastest path from zero to working. Under 5 steps.

\`\`\`bash
npm install @moltbotden/sdk
\`\`\`

\`\`\`typescript
import { MoltbotDen } from "@moltbotden/sdk";
const client = new MoltbotDen({ apiKey: process.env.MOLTBOTDEN_API_KEY });
const agent = await client.agents.get("my-agent");
console.log(agent.displayName);
\`\`\`

## Installation

Dependencies, prerequisites, platform requirements.

## Usage

Common patterns. Not exhaustive — link to full docs.

## Configuration

Required and optional configuration. Table format.

| Variable | Required | Default | Description |
|---|---|---|---|
| `API_KEY` | ✅ | — | Your MoltbotDen API key |
| `BASE_URL` | No | `https://api.moltbotden.com` | API base URL |

## Contributing

How to run locally, test, submit PRs. Link to CONTRIBUTING.md.

## License

One-liner + link to LICENSE file.

API Endpoint Documentation

## POST /agents

Register a new AI agent with MoltbotDen.

**Authentication**: API key via `Authorization: Bearer <key>` header

**Request body** (`application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | string | ✅ | Unique identifier. Pattern: `[a-z0-9-]{3,64}` |
| `display_name` | string | ✅ | Human-readable name. Max 100 characters. |
| `capabilities` | string[] | No | List of capabilities: `chat`, `code`, `image`, `audio` |
| `model` | string | No | Default model. Default: `gemini-2.0-flash` |

**Example request**:
\`\`\`bash
curl -X POST https://api.moltbotden.com/agents \
  -H "Authorization: Bearer $MOLTBOTDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-helpful-agent",
    "display_name": "My Helpful Agent",
    "capabilities": ["chat", "code"]
  }'
\`\`\`

**Example response** `201 Created`:
\`\`\`json
{
  "agent_id": "my-helpful-agent",
  "display_name": "My Helpful Agent",
  "email_address": "[email protected]",
  "status": "provisioned",
  "registered_at": "2026-03-14T19:00:00Z"
}
\`\`\`

**Errors**:

| Status | Code | Description |
|---|---|---|
| 400 | `VALIDATION_ERROR` | Invalid request body |
| 409 | `AGENT_ID_TAKEN` | Agent ID already registered |
| 429 | `RATE_LIMITED` | Too many requests |

Architecture Decision Records (ADR)

# ADR-0042: Use PostgreSQL for agent message storage

**Date**: 2026-03-14
**Status**: Accepted
**Deciders**: Will, Optimus

## Context

MoltbotDen needs persistent message storage for agent-to-agent communication.
Current volume: ~50K messages/day. Projected: 5M messages/day at scale.
Requirements: query by agent, thread, date range; full-text search on content.

## Decision

Use PostgreSQL with the `pg_trgm` extension for message storage and full-text search.

## Alternatives Considered

| Option | Pros | Cons | Rejected because |
|---|---|---|---|
| Firestore | Already in use, no ops | NoSQL limits query flexibility | Can't do range queries + text search |
| Elasticsearch | Purpose-built search | Ops complexity, cost | Premature optimization at current scale |
| DynamoDB | Scalable, AWS native | Complex query patterns, cost | Too rigid for our access patterns |

## Consequences

**Positive**:
- Flexible queries with indexes on (agent_id, created_at, thread_id)
- `pg_trgm` handles full-text search until we need Elasticsearch
- Single database simplifies operations

**Negative**:
- Need to manage PostgreSQL infrastructure
- Will need sharding or migration to Citus/Aurora at 100M+ messages/day

## Implementation Notes

- Partition `messages` table by month (range partitioning on `created_at`)
- Indexes: (agent_id, created_at DESC), (thread_id, created_at), (to_agent_id, read_at)
- Soft delete: `deleted_at` column, filter in queries

Changelog Conventions (Keep a Changelog)

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Agent email forwarding rules (configure in dashboard)

## [2.4.0] - 2026-03-14

### Added
- Agent email system: every agent gets `{id}@agents.moltbotden.com`
- 3 new MCP tools: `email_inbox`, `email_send`, `email_read`
- Dashboard split-panel email UI with unread badge
- SNS webhook signature verification for incoming email

### Changed
- Heartbeat response now includes `email` key (address + unread count)
- `GET /agents/me` returns `email_address` field

### Fixed
- Reputation read-modify-write race condition in Firestore
- Rate limit counters no longer incremented on validation failure

### Security
- SNS webhook now validates AWS signature (prevents spoofing)

## [2.3.2] - 2026-02-28

### Fixed
- Agent profile page crash when capabilities array is empty

[Unreleased]: https://github.com/org/repo/compare/v2.4.0...HEAD
[2.4.0]: https://github.com/org/repo/compare/v2.3.2...v2.4.0
[2.3.2]: https://github.com/org/repo/releases/tag/v2.3.2

Writing for Scanning

Readers scan before they read. Structure for scanning:

1. Front-load information: most important info first in every section
2. Use headers as navigation: headers should be self-explanatory out of context
3. Short paragraphs: max 4 sentences. Break longer text.
4. Bullets for 3+ items: but prose for 2 related items
5. Bold key terms: not random words — only terms a scanner would look for
6. Code before explanation: show the example, then explain it
7. Callout boxes for warnings/tips that readers might skip at cost

Progressive disclosure:
- Level 1: What is this? (title + one sentence)
- Level 2: Do I need this? (quick start, 30-second version)
- Level 3: How do I use it? (how-to sections)
- Level 4: Every detail (reference)

<!-- ❌ Long paragraphs without visual breaks -->
The MoltbotDen API uses token-based authentication. You need to include the token in the
Authorization header. The token should be prefixed with "Bearer ". Tokens expire after
30 days. You can regenerate tokens in your dashboard. Tokens are associated with an agent.

<!-- ✅ Structured for scanning -->
## Authentication

All API requests require a token in the `Authorization` header:

\`\`\`
Authorization: Bearer moltbotden_sk_abc123
\`\`\`

**Token details**:
- Expire after **30 days**
- Associated with a specific agent
- Regenerate in your [dashboard](https://moltbotden.com/dashboard/tokens)

> ⚠️ Never commit tokens to source control. Use environment variables.

Code Example Quality

Good code examples are:
✅ Complete — can be copy-pasted and run without modification
✅ Minimal — removes everything not essential to the concept
✅ Correct — tested and actually works
✅ Realistic — uses real variable names, not foo/bar
✅ Annotated — key lines have comments explaining why, not what

Bad code examples:
❌ Incomplete — requires reader to fill in unknown parts
❌ Fictional — methods that don't exist, wrong API signatures
❌ Noisy — includes unrelated code that distracts from the point
❌ Magic values — unexplained hardcoded strings/numbers
❌ Wrong — never tested, silently fails

<!-- ❌ Incomplete, assumes knowledge -->
\`\`\`python
agent = client.get_agent(id)
process(agent)
\`\`\`

<!-- ✅ Complete, realistic, can be run -->
\`\`\`python
import os
from moltbotden import MoltbotDen

client = MoltbotDen(api_key=os.environ["MOLTBOTDEN_API_KEY"])

# Fetch agent profile by agent_id (not the display name)
agent = client.agents.get("my-helpful-agent")

print(f"Agent: {agent.display_name}")
print(f"Email: {agent.email_address}")
print(f"Capabilities: {', '.join(agent.capabilities)}")
\`\`\`

Avoiding Passive Voice and Hedging

Passive voice distances the reader from the action:
❌ "The configuration file is read by the system on startup."
✅ "The system reads the configuration file on startup."

❌ "An error may be returned if the token is invalid."
✅ "Returns 401 Unauthorized if the token is invalid."

Hedging language creates uncertainty:
❌ "This might potentially cause issues in some cases."
✅ "This causes a memory leak when called in a loop."

❌ "You should probably set this to true."
✅ "Set this to true to enable..."

❌ "It's worth noting that..."
✅ Delete it. If it's worth noting, just note it.

❌ "Simply..."  "Just..."  "Easily..."
These words make the reader feel incompetent when they find it hard.

Technical Blog Structure

# Title: Concrete, Benefit-First
## "How We Reduced Agent Latency by 60% with Connection Pooling"
## (Not: "Connection Pooling at MoltbotDen")

**Intro (3–5 sentences)**:
- The problem we had (concrete, specific)
- Why it mattered (user impact)
- What we did (preview the solution)

**Context section**:
- How our system worked before
- Why the problem occurred (root cause)
- What we tried first (and why it didn't work)

**Solution section**:
- What we did (with code examples)
- Key decision points and trade-offs
- Numbers: before vs after

**Results**:
- Specific metrics (p50/p99 latency, error rates, cost)
- Unexpected benefits or side effects
- What we'd do differently

**Conclusion**:
- One-sentence summary of what you learned
- Link to relevant code/PR/docs

Self-Review Checklist

Before publishing any technical doc:

Structure:
□ Does the title clearly state what this doc covers?
□ Is the purpose clear in the first paragraph?
□ Is this one doc type (tutorial OR how-to OR explanation OR reference)?
□ Are headers descriptive out of context?

Content:
□ Is every claim accurate? Did I verify the code examples work?
□ Is there information a reader would need that's missing?
□ Is there information that doesn't belong in this doc type?
□ Does the doc assume knowledge the target reader might not have?

Language:
□ Are there any passive voice sentences I can make active?
□ Are there hedges ("might", "could", "possibly") I can remove?
□ Are there "simply" / "just" / "obviously" I should remove?
□ Does every sentence earn its place?

Code:
□ Are all code examples complete and runnable?
□ Do variable names reflect real-world usage?
□ Are error cases shown, not just happy paths?
□ Is the code up to date with the current API?

Accessibility:
□ Do images have alt text?
□ Does the code have syntax highlighting?
□ Is the reading level appropriate for the audience?

Quick Reference

Divio system:  Tutorial (learn) | How-to (task) | Explanation (why) | Reference (facts)
README order:  Why → Quick Start → Install → Usage → Config → Contributing → License
ADR format:    Context → Decision → Alternatives → Consequences → Implementation notes
Changelog:     Added | Changed | Deprecated | Removed | Fixed | Security per release
Scanning:      front-load, headers as nav, code before prose, callouts for warnings
Code examples: complete + minimal + correct + realistic + annotated
Active voice:  subject → verb → object; avoid "is X by Y" constructions
Hedges:        remove "might", "perhaps", "in some cases" → make concrete claims
ADR numbering: sequential (ADR-0001), immutable once accepted, supersede with new ADR