Skip to content

Documentation Style Guide

This document defines the tone, voice, structure, and style guidelines for ConnectSoft documentation. It is written for anyone creating or editing documentation in the ConnectSoft ecosystem.

ConnectSoft documentation follows a consistent editorial style: professional, confident, precise, friendly, and pragmatic. We avoid marketing fluff and focus on clarity and actionability.

Important

All documentation should follow this style guide. Consistency in tone, structure, and callout usage makes our documentation more professional and easier to use.

Tone & Voice

  • Professional - Confident, precise, not corporate-bureaucratic
  • Friendly - Approachable, helpful, not condescending
  • Pragmatic - Focus on "why" as well as "what"
  • No hype - Avoid marketing fluff, focus on clarity

Audience

  • Primary - Senior engineers, architects, product/tech leads
  • Assumption - High technical level, avoid over-explaining basics
  • Clarity - Still explain ConnectSoft-specific concepts clearly

Structure

Page Structure

Every page should start with:

  1. Title - # Title (only one per page)
  2. Intro Summary - 1–3 sentences describing:
  3. What this doc is about
  4. Who it's for
  5. What they will get from it

Sectioning

  • # for page title (only one per page)
  • ## for major sections
  • ### for sub-sections
  • Avoid very long sections with no subheadings

Callouts / Admonitions

Use standard MkDocs Material admonitions:

Note / Info

!!! note
    Helpful extra context or side explanations.

Tip / Best Practice

!!! tip
    Recommended practice and why it matters.

Warning

!!! warning
    Things that can break environments, cause data loss, or major confusion.

Important

!!! important
    Key rules we always want enforced (policy-level).

Decision / Abstract

!!! abstract "Decision"
    Summarize the decision, optionally linking to a BDR/ADR file.

Terminology

  • ConnectSoft AI Software Factory or Factory (capital F) - Core platform
  • AI squad or Squad - Virtual team offerings
  • SaaS platform - Identity, Audit, Config, Bot, etc.
  • Define ConnectSoft-specific terms on first use

Examples

See existing documentation for examples of this style in practice.