Varibill Documentation Standards and Style Guide

Introduction

This document defines the official documentation standards and style guidelines for Varibill’s customer-facing documentation.

These guidelines serve as the single source of truth for how all external documentation is written, structured, styled, and presented across Varibill’s customer support and documentation platforms, including:

1. The Freshdesk Knowledge Base and Solution Pages
2. Online support and help articles
3. Customer-facing product guides and how-to documentation, content, and media
4. Downloadable documentation

The goal of this guide is to ensure all Varibill customer documentation is:

1. Consistent in structure, style, and visual presentation
2. Clear, accessible, and easy to navigate
3. Professional and aligned with the Varibill brand
4. Scalable and maintainable as the product evolves

These standards are enforced through a structured documentation pipeline and the Freshdesk portal theme.

All documentation is authored in Markdown and processed through a publishing pipeline (Markdown → Pandoc → HTML → Freshdesk).

Authors are responsible for content structure and clarity. Presentation, layout, and styling are controlled centrally by the documentation system.

Scope & Audience

Applies to:

1. Solution Pages
2. Help articles
3. Guides and onboarding documentation
4. Downloadable PDFs

Documentation Architecture

Varibill documentation is authored and published using a structured pipeline:

Markdown
→ Pandoc
→ HTML
→ Freshdesk Portal (with custom CSS and JavaScript)

Key Principles

1. Markdown is the single source of truth.
2. Authors control content, not presentation.
3. Styling and layout are handled centrally via the portal theme.
4. Documentation must be written to work with the pipeline, not against it.
5. If something cannot be achieved using Markdown, it should be solved at the system level, not the content level.

Authors must not rely on manual formatting or HTML overrides to achieve visual results.

Authoring Constraints

To ensure consistency and maintainability:

• Do NOT use inline HTML unless explicitly required.
• Do NOT apply manual styling (colours, fonts, spacing).
• Do NOT attempt to control layout visually.
• Do NOT embed scripts or custom styling in articles.
• Do NOT duplicate functionality already provided by the portal (e.g. copy buttons, language labels).

All presentation is controlled by the portal theme.

If a layout requirement cannot be achieved using Markdown, it must be raised for system-level implementation.

Document Types

How-to Guides

Step-by-step procedural documentation guiding users through a specific task.

Concept / Overview Articles

High-level explanations describing system behaviour, architecture, or workflows.

FAQ Articles

Short, focused answers to common user questions.

Troubleshooting Guides

Problem-solution structured documentation for resolving known issues.

Release Notes / Announcements

Structured updates outlining new features, improvements, fixes, and performance enhancements.

Writing Style & Language

Voice and Tone

1. Professional and neutral
2. Instructional and solution-focused
3. Direct and conversational:
   • When providing instructions, use “you” and “your”.
   • When describing processes or case studies, use “users”, “the user”, or “customer”.
4. Terminology:
   • When referring to Varibill customers, always use “customer” and avoid “client”.
   • Use “the client” or “the Varibill Client” when referring to the Varibill Client application.

UI Label Formatting

Always reference UI elements exactly as displayed in the application.

Example: Select Billing Documents from the navigation menu.

Terminology Rules

• Always use US English.
• Microsoft writing standards will apply based on Varibill’s product offering, integrations, and scope of growth.
• Maintain consistent terminology across all documentation.
• Avoid internal development terminology in public-facing documentation.

Do’s & Don’ts (System-Level)

Do

• Use Markdown consistently
• Define code block languages
• Follow heading hierarchy
• Keep content structured and predictable

Don’t

• Don’t use inline HTML unless required
• Don’t override styling manually
• Don’t duplicate UI labels already shown in the interface
• Don’t attempt visual layout control

Content Structure Rules

Heading Hierarchy

1. H1: Article title
2. H2: Primary major article sections
   1. H2 font sizing will always be set to 24px bold.
   2. H2 headings will populate the primary right-side in-article table of contents.
3. H3: Subsections
   1. H3 font sizing will always be set to 18px.
   2. H3 headings will populate the secondary right-side in-article table of contents.
4. H4: Third-level subsections
   1. H4 font sizing will always be set to 16px bold italic.
   2. H4 headings will not populate the right-side in-article table of contents.

Paragraph Length

Limit paragraphs to 3-5 lines for readability.

Page Flow

Content should move logically from:

1. Overview / Introduction
2. Actions / Steps
3. Resolution / Closing

Lists, Steps & Procedures

Ordered vs Unordered Lists

• Use numbered lists for sequential steps.
• Use bullet lists for grouped information.

Step Numbering Rules

Each numbered step must contain one primary action. Markdown allows for auto numbering by naming all steps as 1.

Nested Lists

Do not nest more than three levels.

One Action Per Step

Avoid combining multiple actions into a single step.

Visual Design & Formatting Standards

Spacing & Alignment

• Maintain consistent vertical spacing.
• Avoid excessive empty lines.
• Left-align all content, including images, video, and screenshots.

Varibill Sample Image

Images & Media

File Format

• All images must be saved in .png format
• Other formats (JPG, SVG) should only be used when explicitly required

File Naming

• Use CamelCase naming with no spaces
• Do not use special characters or underscores

Example: BillingDocumentsDashboard.png
SourceCollectorSetupStep1.png

Placement & Spacing

• Always include a blank line before and after an image
• Do not place images inline with text

Correct:

Text above

Text below

Image Sizing

Images are sized and rendered automatically by the documentation system.

Authors must not manually resize images.

Images will be categorised into standard display sizes:

• Small (e.g. buttons, icons)
• Medium (e.g. panels, dialogs)
• Large (e.g. full screens)

Specific width rules for each category will be defined and enforced via the portal theme.

Usage Guidelines

• Use images only when they add clarity or support a task
• Avoid excessive or redundant screenshots
• Prefer focused, cropped images over full-screen captures where possible
• Ensure UI elements in screenshots are clearly visible and readable

Storage

• All images must be stored in the /images/ directory within the repository
• Do NOT upload images directly into Freshdesk

Optimisation

• Compress images before committing
• Target file size: under 300KB where possible

Table Formatting

Use tables to present structured data clearly and consistently.

Ensure proper alignment and spacing for readability.

Components & Callouts

Notes

Warnings

Tips and Tricks

Code Blocks

Code examples must use fenced Markdown code blocks with a defined language.

Syntax

code example

Supported Languages

• powershell
• bash
• json
• javascript
• sql
• yaml
• text (fallback)

Rules

1. Always specify a language.
2. Do not manually label code blocks inline. Use headings (e.g. PowerShell, Bash, JSON) when grouping multiple examples.3. Do not apply formatting inside code blocks.
3. Use one code block per language.
4. When multiple languages are provided, group them using headings (e.g. PowerShell, Bash, JSON).

Behaviour

Code blocks are automatically enhanced in the documentation portal with:

• Language labels (e.g. PowerShell, Bash, JSON)
• Copy-to-clipboard buttons
• Consistent styling and spacing

Authors should not attempt to replicate these features manually.

Examples

PowerShell

$basePath = Join-Path $env:APPDATA "DevExpress"
New-Item -ItemType Directory -Path $basePath -Force | Out-Null
Copy-Item -LiteralPath $src -Destination $licensePath -Force

Bash

curl -X GET "https://api.varibill.com/v1/documents" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

JSON

{
  "environment": "production",
  "endpoint": "https://api.varibill.com/v1/customer/billing/documents"
}