Voltimax Platform

Appearance

Documentation Structure ​

The documentation is organized into four main sections, each serving a different audience with different needs.

Overview ​

text
docs/
├── guide/          # User and operator guides
├── integrations/   # System integrator guides
├── developer/      # Core contributor guides
└── reference/      # Auto-generated protocol/schema reference

User Guide (/docs/guide/) ​

Audience: Platform operators, system administrators

Purpose: Help users deploy, configure, and operate the platform.

Content type: Hand-written

Topics:

  • Getting started and deployment
  • Gateway and asset management
  • Security and configuration
  • Operational guides
  • Monitoring and maintenance

Writing style:

  • Focus on practical tasks and outcomes
  • Assume limited technical knowledge
  • Include screenshots where helpful
  • Provide clear prerequisites
  • Link to related configuration

Examples:

  • How to deploy to Azure
  • Managing gateways and devices
  • Configuring authentication
  • Monitoring system health

Integrations (/docs/integrations/) ​

Audience: System integrators, third-party developers

Purpose: Help integrators connect devices and external systems.

Content type: Hand-written

Topics:

  • Compatible devices
  • Protocol integration (Modbus, OCPP, SunSpec)
  • API integration (planned)
  • Custom device integration (planned)
  • Data format specifications

Writing style:

  • Technical but accessible
  • Include working code examples
  • Document API contracts and data formats
  • Provide troubleshooting guidance
  • Link to protocol specifications

Examples:

  • Adding a new Modbus device
  • OCPP charging station setup
  • SunSpec inverter integration
  • Custom protocol handlers

Developer (/docs/developer/) ​

Audience: Core contributors, open-source developers

Purpose: Help developers contribute to the platform.

Content type: Hand-written

Topics:

  • Development setup
  • iot-tools CLI reference
  • Architecture and components (planned)
  • Testing and debugging (planned)
  • Contributing guidelines (planned)
  • Documentation system (this guide)

Writing style:

  • Assume technical expertise
  • Include architecture context
  • Document design decisions
  • Provide debugging tips
  • Reference code locations

Examples:

  • Setting up the development environment
  • Using the iot-tools CLI
  • Writing and running tests
  • Contributing to documentation

Reference (/docs/reference/) ​

Audience: All audiences - protocol/schema lookup

Purpose: Provide comprehensive protocol and schema specifications.

Content type: Auto-generated (do not edit manually)

Topics:

  • Metrics reference (from schemas/metrics/)
  • OCPP 2.1 messages (from OCPP specification)
  • SunSpec models (from SMDX files)
  • Modbus devices (from device YAML files)

Generation: Files in /docs/reference/ are automatically generated and should never be edited manually. See Generation for details.

Examples:

  • Battery metrics definitions
  • OCPP message schemas
  • SunSpec model 101 (Inverter)
  • Modbus device register maps

Choosing the Right Section ​

Use this flowchart to determine where your documentation belongs:

Hand-Written vs. Auto-Generated ​

Hand-Written Documentation ​

All documentation outside /docs/reference/ is hand-written and maintained manually:

  • /docs/guide/ - User and operator guides
  • /docs/integrations/ - Integration guides
  • /docs/developer/ - Developer documentation
  • /docs/protocols/ - Protocol overview (landing page)

When writing hand-written documentation:

Auto-Generated Documentation ​

All files in /docs/reference/ are automatically generated from schemas.

See Generation for:

  • How to regenerate documentation
  • What sources are used
  • Configuration and output paths
  • Adding new generators

Each section has its own sidebar configuration in .vitepress/sidebar/:

  • guide.ts - User/operator navigation
  • integrations.ts - Integrator navigation
  • developer.ts - Developer navigation
  • reference.ts - Auto-generated reference navigation

See VitePress Configuration for details.

Page Structure Rules ​

When to split a page ​

  • It serves two distinct audiences (conceptual vs. reference).
  • It exceeds ~300 lines of prose.
  • A section is frequently deep-linked from other pages.
  • Part of the content is auto-generated.

When to merge pages ​

  • Two pages must always be read together.
  • A page is under ~50 lines.
  • The split exists only for taxonomy, not reader need.

What not to document ​

  • Data that mirrors code, config, or Keycloak - point to the source instead.
  • API signatures without explaining why - link to source for the "what."
  • External specs copied verbatim - document "how we use it" and link upstream.
  • Placeholder pages with no real content - use commented-out sidebar entries.

Prefer cross-links over duplication. If a fact appears in more than one page, it will drift.

See the sidebar structure principles for navigation rules.

Best Practices ​

Do ✅ ​

  • Keep documentation close to code (update docs with features)
  • Put documentation in the section that matches your audience
  • Use the appropriate writing style for each section
  • Link between sections when relevant
  • Update navigation when adding new pages

Don't ❌ ​

  • Mix audiences in the same document
  • Put operator tasks in developer docs
  • Put developer concepts in user guides
  • Create deep navigation hierarchies (max 3 levels)
  • Edit files in /docs/reference/ manually