Voltimax Platform

Appearance

Writing Guidelines ​

This guide covers writing style, formatting conventions, and audience-specific guidelines for Voltimax Platform documentation.

Style Guide ​

These are the platform-specific writing guidelines.

Key Principles ​

  • Write for your audience - Operator, integrator, or developer
  • Be consistent with terminology - Use the same terms throughout
  • Use active voice and present tense - "Configure the gateway" not "The gateway should be configured"
  • Keep sentences short and clear - One idea per sentence
  • Use numbered steps for procedures - Make tasks easy to follow
  • Include prerequisites sections - List requirements upfront

Voice and Tone ​

  • Concise and direct - Get to the point quickly
  • Helpful and practical - Focus on what users need to do
  • Confident but not arrogant - "This configures..." not "This might configure..."
  • Professional but approachable - Avoid jargon, explain when necessary

Formatting Conventions ​

Headings ​

Use semantic heading hierarchy:

markdown
# Page Title (H1 - only one per page)

## Major Section (H2)

### Subsection (H3)

#### Detail Level (H4 - use sparingly)

Best practices:

  • Use ## for major sections
  • Use ### for subsections
  • Avoid going deeper than ####
  • Make headings descriptive and action-oriented

Code Blocks ​

Always specify the language for syntax highlighting:

markdown
```bash
# Shell commands
npm run docs:dev
```

```csharp
// C# code
public class Gateway
{
    public string Id { get; set; }
}
```

```typescript
// TypeScript code
const config = {
  port: 5173
}
```

Best practices:

  • Use language hints for all code blocks
  • Include comments to explain non-obvious code
  • Keep examples focused and minimal
  • When code examples are necessary, verify they compile against the current codebase

Lists ​

Use ordered lists for sequential steps:

markdown
1. Clone the repository
2. Install dependencies
3. Run the development server

Use unordered lists for non-sequential items:

markdown
- .NET 10 SDK
- Docker Desktop
- Azure CLI

Tables ​

Use tables for structured data:

markdown
| Section | Audience | Type |
|---------|----------|------|
| Guide | Operators | Hand-written |
| Reference | All | Auto-generated |

Diagrams ​

Always use Mermaid for diagrams. Never use ASCII art, box-drawing characters, or image-based diagrams:

markdown
```mermaid
flowchart LR
    A[Gateway] --> B[API] --> C[Database]
```

Mermaid renders natively in VitePress and stays maintainable as text.

Emoji ​

Do not use emoji in documentation. Use VitePress callouts for emphasis instead. Exception: ✅/❌/⚠️ are acceptable as status indicators in tables (e.g. checklists, good/bad examples).

Code Examples ​

Avoid inline code examples where possible - they go stale quickly as APIs change. Prefer linking to real source files or tests. When a code example is truly necessary (e.g. a quick-start showing a registration pattern), keep it minimal and note which source file it mirrors so it can be verified.

Callouts ​

VitePress supports special callouts:

markdown
::: tip
Use this template for task-based guides.
:::

::: warning
Never edit files in `/docs/reference/` manually.
:::

::: danger
This action is irreversible.
:::

::: info
Most reference documentation is auto-generated.
:::

Use descriptive link text:

Good: See the [VitePress configuration guide](./vitepress.md)

Bad: See [this guide](./vitepress.md) or Click [here](./vitepress.md)

Internal links:

markdown
[Link text](/guide/getting-started)

External links:

markdown
[VitePress](https://vitepress.dev/)

Writing by Section ​

Each documentation section targets a different audience with different expectations. See Documentation Structure for the full breakdown of audiences, writing style, and examples per section.

Best Practices ​

Do ✅ ​

  • Use active voice - "Configure the gateway" not "The gateway should be configured"
  • Link to source files - Prefer linking to real code over inline examples
  • Add screenshots for UI tasks - Visual aids help
  • Link to related documentation - Build a documentation web
  • Keep it focused - One topic per page
  • Use templates - Ensure consistency
  • Update docs with code - Keep them in sync

Don't ❌ ​

  • Write walls of text - Break into sections with headings
  • Assume prior knowledge - List prerequisites explicitly
  • Use jargon without explanation - Define technical terms
  • Duplicate content - Write a fact once and cross-link
  • Forget to update navigation - Add new pages to sidebars
  • Add inline code that will drift - Link to source instead
  • Mix audiences - Write for one audience per document

Resources ​