Voice & Style

Writing guidelines for Vant content.

Our Tone

We’re engineers who are also helpful. Clear. Direct. Slightly informal when appropriate, serious when it matters.

We are transparent that AI agents contribute to this project.

Principles

1. Use Short Dashes

Use the plain hyphen in prose. Avoid em and en dashes entirely.

2. Avoid AI Cliches

These phrases are overused:

Just say what you mean.

3. Be Specific, Not Abstract

4. State Facts, Not Hype

5. Active Voice

Use subject-verb-object. Present tense.

6. Code Is Documentation

Show, don’t just tell. Include working commands.

7. Write for Humans and AIs

• A human should feel respected
• An AI should get clear instructions

Formatting

Every guide needs frontmatter for the docs site:

---
version: 0.8.6
permalink: /guides/my-guide
layout: default
title: My Guide Title
nav_order: 75
---

Always include all 5 fields. Guides without frontmatter won’t render on docs.creadev.org.

Numbered Lists in Code Blocks

Never use numbered lists (1. 2. 3.) inside markdown code blocks. Use dashes instead:

Steps to run:
- Clone: git clone https://github.com/dhaupin/vant.git
- Configure: cp config.example.ini config.ini

Why: Markdown parsers may render numbered lists incorrectly inside fenced code blocks.

Avoid Placeholder Content

Never use “This section covers…” as a section intro. Write actual content:

Code Blocks Need Briefs

Every code block needs a 1-sentence explainer before it:

Check system health:

vant health

Why: Readers need context, not just commands.

Code Block Best Practices

Include:

• Brief context (what does this do?)
• Language hint when it matters
• Explain key parts after the block
• Show expected output when helpful

Don’t:

• Just dump code with no explanation
• Assume the reader knows the context
• Skip error handling in examples

Example - Good code block documentation:

Install Vant from the repo and link the CLI:

git clone https://github.com/dhaupin/vant.git && cd vant
npm ci && npm link

This puts the vant command on your PATH. Use npm link so CLI access works anywhere.

Example output:

$ vant --version
0.8.6

Source of Truth

The docs system (/docs/) is the source of truth for all documentation.

• README.md references docs, not the other way around
• Keep detailed content in docs
• README provides quick reference with links to full docs

Why: Docs can be rendered with Jekyll (syntax highlighting, navigation, search). README is a single file.

Focus Areas

Include:

• How to use Vant (clear steps)
• What problems Vant solves (specific)
• Technical details (accurate)
• Tradeoffs (honest)

Avoid:

• Vague value propositions
• Over-promising
• Buzzwords

Example

Show don’t vs shouldn’t.

Before (Cliche)

“Discover the future of AI memory with Vant - the ultimate solution to unlock seamless persistent intelligence across your agentic workflows.”

After (Our Style)

“Vant stores your AI’s memory in Git. Each session inherits the previous one. Use branches to experiment with different brain configs.”

Applying This Guide

Check all content for:

• Em dashes replaced with hyphens
• Cliche phrases removed
• Specific over abstract
• Active voice

Documenting Sections

Every section header should have a 1-2 sentence intro that answers:

1. What is this section about?
2. Why does the reader need to know it?

Example

For example, here’s a properly documented section:

## Installation

Install Vant locally or via Docker.

### Local Install
For local development:

What’s NOT needed:

• Long intros (save for index page)
• Multiple paragraphs before first step

Common Doc Blocks

Related

• CLI Reference - All commands
• Documentation - Docs index