Voltimax Platform

Appearance

Documentation Templates ​

These templates define the expected structure for different types of documentation pages.

Available Templates ​

How-To Guide ​

Use when: You need to explain how to complete a specific task.

Structure:

  • Clear, action-oriented title
  • Prerequisites
  • Step-by-step instructions
  • Expected results
  • Troubleshooting (if needed)

Examples:

  • How to configure a gateway
  • How to add a new device
  • How to set up monitoring

Quickstart ​

Use when: You want to get users up and running quickly.

Structure:

  • Minimal prerequisites
  • Fastest path to success
  • Simple, clear steps
  • Quick verification
  • Next steps

Examples:

  • Getting started with the platform
  • Quick device setup
  • API quickstart

Tutorial ​

Use when: You want to teach concepts through hands-on learning.

Structure:

  • Learning objectives
  • Complete working example
  • Detailed explanations
  • Progressive complexity
  • What you learned

Examples:

  • Building your first integration
  • Creating a custom control strategy
  • End-to-end workflow tutorial

Reference ​

Use when: You need structured, comprehensive reference documentation.

Structure:

  • Overview
  • Detailed specifications
  • Parameters/properties
  • Examples
  • Related topics

Examples:

  • API reference
  • Configuration reference
  • Protocol specifications

TIP

Most reference documentation is auto-generated from schemas. Use this template only for hand-written reference material.

Troubleshooting ​

Use when: You need to help users solve problems.

Structure:

  • Problem symptoms
  • Possible causes
  • Solutions (ordered by likelihood)
  • Verification steps
  • Prevention tips

Examples:

  • Gateway connectivity issues
  • Device communication problems
  • Common configuration errors

API Getting Started ​

Use when: You need to onboard developers to an API.

Structure:

  • API overview
  • Authentication setup
  • First API call
  • Common use cases
  • Next steps

Examples:

  • REST API getting started
  • WebSocket API introduction
  • GraphQL API quickstart

Choosing the Right Template ​

Use this flowchart to select the appropriate template:

Using Templates ​

1. Create the Page ​

Create a new Markdown file in the appropriate directory and use the structure above as your starting point.

2. Fill in the Content ​

Replace all placeholder text (marked with [square brackets]):

PlaceholderReplace With
[Product name]Voltimax IoT Platform
[Task name]Your specific task
[Prerequisites]Actual prerequisites
[Step 1]Actual step-by-step instructions
[Expected result]What the user should see

Example:

markdown
# How to [Task Name]
↓
# How to Configure a Gateway

3. Follow the Style Guide ​

Refer to our Writing Guidelines for:

  • Writing tone and voice
  • Formatting conventions
  • Terminology standards
  • Code sample guidelines

4. Add to Navigation ​

Update the appropriate sidebar file:

Documentation TypeSidebar File
User guides.vitepress/sidebar/guide.ts
Integration guides.vitepress/sidebar/integration.ts
Developer guides.vitepress/sidebar/developer.ts

See VitePress Configuration for details.

5. Test Locally ​

Start the development server:

powershell
cd docs
npm run docs:dev

Visit http://localhost:5173 to verify your changes.

Template Customization ​

While templates provide structure, feel free to adapt them:

You Can ​

  • Add sections specific to your topic
  • Remove sections that don't apply
  • Adjust depth based on complexity
  • Combine templates if needed (e.g., Tutorial + Troubleshooting)
  • Reorganize sections to improve flow

You Cannot ​

WARNING

Don't remove critical sections:

  • Prerequisites
  • Step-by-step instructions (for how-tos)
  • Learning objectives (for tutorials)
  • Problem/solution pairs (for troubleshooting)

Best Practices ​

Do ✅ ​

  • Use active voice ("Configure the gateway" not "The gateway should be configured")
  • Link to source files instead of inline code examples
  • Add screenshots for UI tasks
  • Link to related documentation
  • Keep it focused on one topic
  • Follow the template structure
  • Replace all placeholder text

Don't ❌ ​

  • Mix templates in confusing ways
  • Skip the template structure
  • Write walls of text without headings
  • Assume prior knowledge (list prerequisites)
  • Forget to update navigation
  • Leave placeholder text in published docs

Template Examples ​

How-To Example ​

markdown
# How to Add a Modbus Device

This guide shows how to connect a Modbus RTU device to your gateway.

## Before you start

Ensure you have:
- Gateway with Modbus support enabled
- Modbus device connected via RS485
- Device register map documentation

## Add the device

1. Open the gateway web interface
2. Navigate to **Devices** > **Add Device**
3. Select **Modbus RTU** as the device type
4. Configure the connection:
   ```yaml
   port: /dev/ttyUSB0
   baudRate: 9600
   parity: none
  1. Click Add Device

Verify the connection ​

Check the device status in the dashboard. It should show as Connected.

Next steps ​

  • Configure device metrics (coming soon)
  • Set up monitoring (coming soon)

Quickstart Example ​

markdown
# Quickstart: Deploy Your First Gateway

Get a gateway up and running in 5 minutes.

## Prerequisites

- .NET 10 SDK installed
- Docker Desktop running

## Deploy the gateway

1. Clone the repository:
   ```bash
   git clone https://github.com/voltimax/platform.git
   cd platform

  1. Start the gateway:

    bash
    docker compose up -d

  2. Open the web interface at http://localhost:5000

You should see the gateway dashboard.

Quickstart - Next steps ​

  • Add your first device (coming soon)
  • Configure security (see Guide)

Getting Help ​

If you need help with templates:

  • Check existing documentation for examples of each template type
  • Review the Writing Guidelines
  • Ask in team chat or create an issue

Resources ​