| name | writing-docs |
| description | Write and edit documentation articles in the docs/ directory for Sloppy users. Use when creating new doc pages, editing existing guides, or when the user mentions docs, documentation, articles, or guides for the docs/ folder. |
Writing Documentation Articles
Sloppy docs live in docs/, built with VitePress, and target regular users — not developers of Sloppy itself. Write to help someone set up, configure, and use the product.
Before Writing
- Read
docs/.vitepress/config.ts to understand the current sidebar structure and section grouping.
- Read 1–2 existing articles from the same sidebar section to match tone and depth.
- Identify which
sloppy.json config keys are relevant — read the actual config model in Sources/ if needed.
Language
All articles must be written in English only.
File Setup
Every article needs YAML frontmatter:
---
layout: doc
title: Short Page Title
---
After creating or moving a file, update the sidebar in docs/.vitepress/config.ts — add the new entry to the correct section and position.
Structure Template
---
layout: doc
title: Feature Name
---
# Feature Name
One-paragraph overview: what this feature is and why a user would care.
## How it works
Plain-language explanation of the core concept. Avoid internal module names
and implementation details. Focus on what the user experiences.
## Setup / Getting started
Step-by-step instructions with numbered steps. Include config snippets
and Dashboard UI paths where applicable.
## Configuration
Show the relevant slice of `sloppy.json` with a table explaining each field.
## Related
- [Link to related article](/section/slug)
Not every section is required — adapt to the topic. Short articles (like setup guides) may skip "How it works" if the intro covers it.
Writing Style
Tone
- Second person: "you", "your" — address the reader directly.
- Present tense: "Sloppy stores memory locally" not "Sloppy will store".
- Conversational but precise. Explain what and why, not how the code works internally.
What to avoid
- Internal module names (
CoreRouter, ChannelRuntime, SQLiteStore) unless essential for the reader.
- Implementation details (actor isolation, Swift protocols, internal data structures).
- Jargon without explanation — if a term is necessary, define it on first use.
- Walls of text — break long explanations into short paragraphs (2–4 sentences).
What to include
- Practical examples: real
sloppy.json snippets, curl commands, Dashboard paths.
- Tables for reference data (config fields, command lists, comparison).
- ASCII flow diagrams when showing how data moves through the system.
- Mermaid diagrams (VitePress supports them) for more complex flows or architectures.
Config Snippets
Show only the relevant slice of sloppy.json, not the entire file. Accompany every snippet with a field table:
### Provider settings (`memory.provider`)
| Setting | Default | What it controls |
|---|---|---|
| `mode` | `local` | Where semantic indexing happens: `local`, `http`, or `mcp` |
| `endpoint` | — | URL of the external HTTP memory service |
Use — for fields with no default. Show realistic values in JSON examples, not placeholder "...".
Diagrams
ASCII diagrams
Use for simple linear flows (message routing, request lifecycle):
User (Telegram)
│
▼
Gateway Plugin
│
▼
Channel Runtime ── processes message
│
▼
Agent Response
Use box-drawing characters (│, ▼, ──, ─) for clean rendering.
Mermaid diagrams
Use for branching logic, state machines, or architecture overviews:
```mermaid
graph LR
A[User Message] --> B{Has Binding?}
B -->|Yes| C[Route to Channel]
B -->|No| D[Drop Message]
```
Keep diagrams focused — no more than 8–10 nodes. If it needs more, split into multiple diagrams or simplify.
Cross-Links
Link to related pages when referencing a concept covered elsewhere:
See [About Channels](/channels/about) for details on bindings and access control.
Add a ## Related section at the bottom for broader connections. Use relative VitePress links (no .md extension, no domain).
VitePress Containers
Use sparingly for important callouts:
::: tip
Short helpful tip.
:::
::: warning
Something the user should be careful about.
:::
::: danger
Something that can cause data loss or breaking changes.
:::
Sidebar Registration
After creating a new article, add it to docs/.vitepress/config.ts in the correct sidebar group:
{
text: "Section Name",
items: [
{ text: "Your New Page", link: "/section/your-new-page" }
]
}
Checklist
Before finishing an article:
