Documentation Style Guide

This guide defines the writing standards for Voltimax IoT Platform documentation. Following these guidelines ensures consistency, clarity, and professionalism across all documentation.

TIP

For detailed template usage, see Documentation Templates.

Voice and Tone

Active Voice

Use active voice to be direct and clear.

✅ Good: "Configure the gateway to connect to devices."
❌ Bad: "The gateway should be configured to be connected to devices."

Present Tense

Write in present tense for actions.

✅ Good: "The gateway sends metrics to the API."
❌ Bad: "The gateway will send metrics to the API."

Direct Address

Address the reader directly using "you."

✅ Good: "You can configure the gateway using the CLI."
❌ Bad: "Users can configure the gateway using the CLI."

Conversational but Professional

Be friendly and approachable, but maintain professionalism.

✅ Good: "Let's start by setting up your first device."
❌ Too casual: "Yo, time to hook up your first device!"
❌ Too formal: "One must commence the initialization procedure for the primary device entity."

Formatting Conventions

Headings

Use sentence case for headings (capitalize only the first word and proper nouns).

✅ Good: "Getting started with the platform"
❌ Bad: "Getting Started With The Platform"

Code Elements

Use backticks for inline code elements:

markdown

Use the `iot-tools` command to generate documentation.
The `Gateway.Id` property identifies the gateway.
Set `EnableMetrics` to `true` in the configuration.

Code Blocks

Use fenced code blocks with language identifiers:

markdown

```csharp
var gateway = new Gateway
{
    Id = "gateway-001",
    Name = "Main Gateway"
};
```

```powershell
.\cli.ps1 generate --metrics
```

```json
{
  "gatewayId": "gateway-001",
  "status": "online"
}
```

File Paths

Use inline code for file paths and wrap long paths:

markdown

Edit the configuration in `src/Gateway/appsettings.json`.

UI Elements

Use bold for UI elements:

markdown

Click **Settings** > **Configuration** > **Devices**.
Select the **Enable Monitoring** checkbox.

Lists

Bulleted lists for unordered items:

Use for features
Use for options
Use for requirements

Numbered lists for sequential steps:

First, install the prerequisites
Next, configure the gateway
Finally, verify the connection

Definition lists for term/definition pairs:

markdown

**Gateway**: The edge device that collects data from assets.

**Asset**: A physical device (battery, inverter, etc.) monitored by the platform.

**Metric**: A measurement collected from an asset.

Callouts

Use VitePress containers for important information:

markdown

::: tip
This feature is available in version 2.0 and later.
:::

::: warning
Changing this setting requires a gateway restart.
:::

::: danger
Do not modify generated files directly. Your changes will be overwritten.
:::

::: info
For more details, see the [API Reference](/reference/api/).
:::

Links

Internal links use relative paths:

markdown

See [Getting Started](./getting-started.md).
Refer to [Metrics Reference](../reference/metrics/).

External links include descriptive text:

markdown

Learn more in the [OCPP 2.1 Specification](https://www.openchargealliance.org/).

Avoid "click here" links:

❌ Bad: "For more information, click here."

✅ Good: "See the API documentation for more information."

Terminology

Consistent Terms

Use these standard terms consistently:

Use This	Not These
gateway	edge device, collector, agent
asset	device (when referring to monitored equipment)
metric	measurement, data point, telemetry
API	API, API, REST API (unless specifically referring to REST)
user	customer, client (unless specifically referring to B2B)
you	the user, one, developers (when addressing reader)

Platform-Specific Terms

Voltimax IoT Platform (first mention) > the platform (later mentions)
iot-tools CLI (not "command-line tool" or "command line")
VitePress (not "Vitepress" or "vitepress")

Capitalization

Capitalize proper nouns and product names:

Voltimax IoT Platform
GitHub
Azure
.NET
Visual Studio Code

Don't capitalize generic terms:

gateway (not Gateway)
battery (not Battery)
configuration (not Configuration)

Exception: Capitalize when referring to code identifiers:

markdown

The `Gateway` class represents a gateway instance.

Writing Guidelines

Be Concise

Get to the point quickly. Remove unnecessary words.

✅ Good: "Configure the gateway using the CLI."
❌ Wordy: "You can go ahead and configure the gateway by using the command-line tool."

One Idea Per Sentence

Keep sentences focused and readable.

✅ Good: "Install the CLI. Then configure your gateway."
❌ Complex: "Install the CLI and then configure your gateway, which will allow you to manage devices."

Use Lists

Break up dense information into scannable lists.

✅ Good:

markdown

Prerequisites:
- .NET 10 SDK or later
- Docker Desktop
- Valid API credentials

❌ Bad:

markdown

Before you begin, make sure you have .NET 10 SDK or later, Docker Desktop, and valid API credentials.

Provide Context

Explain why before explaining how.

✅ Good:

markdown

## Configure Gateway Metrics

The gateway collects metrics from connected assets. By default, metrics are sent every 60 seconds. You can adjust this interval based on your monitoring requirements.

To configure the metrics interval:
1. ...

❌ Bad:

markdown

## Configure Gateway Metrics

1. Open appsettings.json
2. Change MetricsInterval to your desired value
3. ...

Include Examples

Show, don't just tell. Provide code examples and sample output.

API Response

The API returns a JSON object with the device status:

json

{
  "deviceId": "battery-001",
  "status": "charging",
  "stateOfCharge": 75.5
}

Anticipate Questions

Address common questions proactively.

markdown

## Device Connection Issues

**Q: Why isn't my device connecting?**

Check these common causes:

1. Verify the device IP address is correct
1. Ensure the device is powered on
1. Check firewall settings allow Modbus traffic

## Code Examples

### Complete and Tested

All code examples should:
- Be complete (not pseudocode)
- Be tested and verified working
- Include necessary imports/usings
- Show expected output when relevant

### Realistic

Use realistic values and scenarios:

✅ **Good:**

```csharp
var battery = new Battery
{
    Id = "battery-001",
    Capacity = 10.0, // kWh
    Manufacturer = "ACME Energy"
};

❌ Bad:

csharp

var battery = new Battery
{
    Id = "foo",
    Capacity = 123,
    Manufacturer = "bar"
};

Annotated

Add comments to explain non-obvious parts:

csharp

// Connect to the gateway's Modbus TCP interface
var client = new ModbusClient("192.168.1.100", 502);

// Read holding registers 40001-40010 (10 registers)
var registers = await client.ReadHoldingRegistersAsync(0, 10);

Structure

Progressive Disclosure

Start simple, add complexity gradually:

Basic example - Show the simplest working code
Full example - Show real-world usage
Advanced - Show optimization or edge cases

Scannable Content

Use headings, lists, and whitespace to make content scannable:

Use heading hierarchy correctly (H1 > H2 > H3)
Break up long sections with subheadings
Use lists for parallel information
Add whitespace between sections

Prerequisites First

Always list prerequisites before instructions:

Deploy the Gateway

Prerequisites

Docker 20.10 or later
Valid Azure credentials
Network access to Azure

Steps

Pull the Docker image:
bash
```
docker pull voltimax/gateway:latest
```

Common Mistakes to Avoid

❌ Assumptions

Don't assume knowledge. State prerequisites explicitly.

❌ Jargon Without Definition

Define technical terms on first use:

✅ Good: "The gateway uses Modbus TCP (a protocol for industrial device communication) to connect to assets."

❌ Inconsistent Terminology

Don't switch between terms for the same concept:

❌ Bad: "Configure the gateway... The edge device will then... The collector sends..."
✅ Good: "Configure the gateway... The gateway will then... The gateway sends..."

❌ Passive Voice

Avoid passive constructions:

❌ Bad: "Metrics are collected by the gateway."
✅ Good: "The gateway collects metrics."

❌ Future Tense

Use present tense, not future:

❌ Bad: "The gateway will send metrics to the API."
✅ Good: "The gateway sends metrics to the API."

❌ Gendered Pronouns

Use gender-neutral language:

❌ Bad: "When a user logs in, he should..."
✅ Good: "When a user logs in, they should..." or "When you log in, you should..."

Documentation Types

How-To Guides

Task-oriented
Step-by-step
Assumes basic knowledge
Goal: Help user complete a specific task

Tutorials

Learning-oriented
Comprehensive
Teaches concepts
Goal: Help user understand how to work with the platform

Reference

Information-oriented
Comprehensive
Authoritative
Goal: Provide technical specifications

Troubleshooting

Problem-oriented
Diagnostic approach
Solutions-focused
Goal: Help user resolve issues

Review Checklist

Before publishing documentation:

[ ] Spell check completed
[ ] Grammar check completed
[ ] All links tested
[ ] All code examples tested
[ ] Terminology consistent
[ ] Screenshots current
[ ] Headings follow hierarchy
[ ] Voice is active
[ ] Tense is present
[ ] Navigation updated
[ ] Follows appropriate template

Resources

Reference Materials

Good Docs Style Guide - Full Good Docs Project style guide
Documentation Templates - Available templates
Documentation Guide - Complete documentation system guide

Writing Tools

Grammarly - Grammar and style checking
Hemingway Editor - Readability analysis
Vale - Automated style guide enforcement

External Guides

Microsoft Writing Style Guide (see Microsoft docs)
Google Developer Documentation Style Guide
Write the Docs

Documentation Style Guide ​

Voice and Tone ​

Active Voice ​

Present Tense ​

Direct Address ​

Conversational but Professional ​

Formatting Conventions ​

Headings ​

Code Elements ​

Code Blocks ​

File Paths ​

UI Elements ​

Lists ​

Callouts ​

Links ​

Terminology ​

Consistent Terms ​

Platform-Specific Terms ​

Capitalization ​

Writing Guidelines ​

Be Concise ​

One Idea Per Sentence ​

Use Lists ​

Provide Context ​

Include Examples ​

API Response ​

Anticipate Questions ​

Annotated ​

Structure ​

Progressive Disclosure ​

Scannable Content ​

Prerequisites First ​

Deploy the Gateway ​

Prerequisites ​

Steps ​

Common Mistakes to Avoid ​

❌ Assumptions ​

❌ Jargon Without Definition ​

❌ Inconsistent Terminology ​

❌ Passive Voice ​

❌ Future Tense ​

❌ Gendered Pronouns ​

Documentation Types ​

How-To Guides ​

Tutorials ​

Reference ​

Troubleshooting ​

Review Checklist ​

Resources ​

Reference Materials ​

Writing Tools ​

External Guides ​

Documentation Style Guide

Voice and Tone

Active Voice

Present Tense

Direct Address

Conversational but Professional

Formatting Conventions

Headings

Code Elements

Code Blocks

File Paths

UI Elements

Lists

Callouts

Links

Terminology

Consistent Terms

Platform-Specific Terms

Capitalization

Writing Guidelines

Be Concise

One Idea Per Sentence

Use Lists

Provide Context

Include Examples

API Response

Anticipate Questions

Annotated

Structure

Progressive Disclosure

Scannable Content

Prerequisites First

Deploy the Gateway

Prerequisites

Steps

Common Mistakes to Avoid

❌ Assumptions

❌ Jargon Without Definition

❌ Inconsistent Terminology

❌ Passive Voice

❌ Future Tense

❌ Gendered Pronouns

Documentation Types

How-To Guides

Tutorials

Reference

Troubleshooting

Review Checklist

Resources

Reference Materials

Writing Tools

External Guides