Documentation Style Guide

The canonical guide defining the writing standards, structure, versioning, and terminology for all Qmova documentation.

Version 1.0.0Internal

Documentation Style Guide

This document is the single source of truth for the Qmova documentation ecosystem. All future documentation must adhere to these standards to ensure consistency, accuracy, and a premium user experience.


1. Documentation Philosophy

Qmova's documentation is treated as an extension of the product itself. The quality of our documentation must resemble the highest industry standards, akin to Stripe, Vercel, Notion, GitHub, Cloudflare, Atlassian, and Linear.

All documentation must be:

  • Accurate: Factual and up-to-date with current product capabilities.
  • Concise: Respect the reader's time. Get straight to the point.
  • Technically Correct: Verified examples, valid endpoints, and working code.
  • Legally Careful: Do not invent capabilities, make unsupported claims, or fabricate certifications.
  • Human-Readable: Use clear, approachable language over jargon.
  • Enterprise Quality: Highly structured, professional, and consistent.
Marketing Language

Avoid marketing fluff. Do not use hyperbolic terms like "revolutionary," "best-in-class," or "magic." Documentation is for enabling users, not selling to them.


2. Documentation Hierarchy

Our documentation is organized into clear top-level categories. Every document must fall under one of the following hierarchies:

| Category | Purpose | | :--- | :--- | | Product Documentation | Guides, tutorials, and feature explanations for using the Qmova platform. | | API Documentation | Technical references for developers building integrations with Qmova. | | Trust Center | Information regarding Qmova's security posture, reliability, and data handling. | | Legal Center | Authoritative legal policies, agreements, and Terms of Service. | | Compliance | Details on our adherence to frameworks like SOC2, ISO 27001, and HIPAA. | | Help Center | Answers to frequently asked questions and troubleshooting steps. | | Release Notes | Chronological changelogs documenting new features, fixes, and deprecations. | | Internal Documentation | Engineering, QA, and operational guides strictly for Qmova staff (like this document). |


3. Standard Document Structure

Every public-facing document must follow a predictable layout to ensure a consistent user experience.

Required Frontmatter

All documents must include MDX frontmatter defining the title, description, version, status, and order.

Document Body

When applicable, the structure of the document should follow this order:

  1. Title (H1): The core subject of the document.
  2. At a Glance: A brief 1-2 sentence summary of what the document covers.
  3. Intended Audience: E.g., "For Workspace Admins" or "For Developers." (Omit if universal).
  4. Table of Contents: Autogenerated by the documentation engine.
  5. Definitions / Prerequisites: Any terms or setup required before proceeding.
  6. Main Content: The core guide, policies, or technical references.
  7. Contact Information: Where to reach support or legal for questions.
  8. Related Documents: Links to tangential reading.
  9. Version History: Track changes for transparency (required for Legal/Compliance).

4. Canonical Terminology

To maintain consistency across all surfaces, use the following official definitions and capitalize them exactly as shown:

| Term | Official Definition | | :--- | :--- | | Customer | The business or organization paying for Qmova. | | Workspace | The top-level administrative boundary for a Customer. | | Tenant | The technical representation of a Customer in our database architecture. Use only in engineering contexts; use "Workspace" externally. | | Visit | A single instance of a Visitor interacting with a Location. | | Visit Lifecycle | The end-to-end state machine of a Visit (e.g., Scheduled → Checked In → In Progress → Completed). | | Appointment | A Visit scheduled in advance for a specific time slot. | | Walk-in | A Visit initiated on-site without prior scheduling. | | Queue | The logical grouping and ordered list of waiting Visits. | | QR Check-in | The mechanism by which a Visitor scans a QR code to initiate or claim a Visit. | | Service | A configurable offering that a Visitor can select (e.g., "Consultation", "Pickup"). | | Staff Member | A user who operates the Qmova platform on behalf of the Customer. | | Visitor | The end-consumer receiving service from the Customer. | | Audit Log | The immutable record of critical events within a Workspace. | | Notification | An automated message sent via SMS, Email, or WhatsApp. | | Integration | A connection between Qmova and a third-party system. | | Role | A predefined set of Permissions assigned to a Staff Member. | | Permission | A specific granular right to perform an action (e.g., location.edit). |


5. Writing Style

  • Prefer active voice: "The system generates a token," not "A token is generated by the system."
  • Prefer plain English: Use short, simple words.
  • Avoid unnecessary legal jargon: Except in strict Legal Center documents.
  • Avoid unexplained acronyms: Always spell out an acronym on its first use (e.g., "Role-Based Access Control (RBAC)").
  • Explain concepts first: Do not assume the user knows how our architecture works.
  • Use consistent heading levels: Never skip heading levels (do not jump from H2 to H4).
  • Keep paragraphs short: Aim for 3-4 sentences maximum.
  • Use tables: Tabular data is always easier to scan than comma-separated text.
  • Diagrams: Use diagrams only to map complex workflows. Do not use diagrams to replace text; use them to complement text.

6. Cross-Reference Rules

  • Do not duplicate explanations: If a concept is explained in detail elsewhere, link to it. Do not maintain two versions of the truth.
  • Use the <RelatedDocs /> component: Place tangential but relevant links at the bottom of the page.
  • Authoritative sources: When discussing data retention in a product guide, link to the official Privacy Policy rather than summarizing the legal constraints yourself.

7. Versioning

We utilize Semantic Versioning (SemVer) for all documentation to track major shifts in policy or technical implementation.

  • Major (e.g., 2.0.0): Complete rewrites, breaking API changes, or foundational shifts in legal policies requiring re-acceptance.
  • Minor (e.g., 1.1.0): Substantial additions like new sections, new endpoints, or expanded legal clauses that do not invalidate previous terms.
  • Patch (e.g., 1.0.1): Typo fixes, broken link repairs, or minor clarification of existing text.

8. Status Labels

Use the status field in the frontmatter to indicate the document's readiness and visibility.

  • Draft: Work in progress. Not meant to be read by the intended audience yet.
  • Internal: Polished, but strictly for internal company use (like this guide).
  • Public: Fully reviewed and published for the world to see.
  • Deprecated: This document refers to outdated features or policies and will be removed soon.
  • Archived: Historical documentation kept strictly for legal or audit purposes.

9. Callout Standards

We use the <Callout /> component to draw attention to critical information. Use these specific variants appropriately:

  • Info: For general context or "good to know" information.
  • Tip: For best practices, shortcuts, or optimization advice.
  • Note: For specific exceptions or edge cases to a rule.
  • Warning: For actions that could cause confusion, minor data loss, or configuration issues.
  • Important: For critical legal, security, or billing constraints.
  • Roadmap: For features that are planned but not yet released.
Example Usage

Use Tips sparingly so they remain impactful. Overusing callouts causes banner blindness.


10. Diagram Standards

Diagrams should complement text, not replace it. Our preferred standard is Mermaid.js, which renders natively in our documentation engine.

  • Flow Diagrams: Best for Visit Lifecycles and user journeys.
  • Architecture Diagrams: Best for illustrating integrations and infrastructure.
  • Data Flow Diagrams: Best for security and privacy documentation.
Accessibility

Because diagrams cannot be easily read by screen readers, you must always provide a text-based explanation of the diagram's flow immediately below or above it.


When drafting or updating documents in the Legal Center or Compliance hierarchies:

  • Do not claim unachieved certifications: If an audit is in progress, state "In Progress" or "Planned."
  • Distinguish current vs. roadmap: Never state a feature exists legally if it is only on the roadmap.
  • Consistent terminology: Use the exact definitions from Section 4.
  • Comprehensibility: Strive for plain English where legally permissible.
  • Unsupported promises: Never guarantee 100% uptime, zero vulnerabilities, or absolute security. Use industry-standard SLA language.

12. Security Documentation Rules

Security documentation must focus on actual, verifiable controls rather than marketing assurances.

When writing for the Trust Center, specifically document:

  • Authentication: How users verify identity (e.g., Google OAuth, OTP).
  • Authorization: How the system enforces boundaries (e.g., RBAC, Tenant isolation).
  • Encryption: Algorithms in transit (TLS 1.3) and at rest (AES-256).
  • Audit Logging: What events are tracked and for how long.
  • Monitoring & Incident Response: How we detect and react to threats.
  • Backups: Frequency and restoration testing protocols.

13. Product Documentation Rules

  • Feature scope: Focus on how to use a feature and why it matters to the Customer's business.
  • Terminology: Stick to the canonical UI terms. If a button says "Save Configuration", reference "Save Configuration", not "Update Settings".
  • Implementation details: Avoid explaining how the backend works unless it directly affects the user's workflow.

14. API Documentation Rules

API Documentation must be precise and developer-friendly. Every endpoint document must include:

  • Authentication requirements: (e.g., Bearer Token).
  • Request parameters: Document path variables, query params, and request body schema.
  • Response schema: Document the exact JSON structure returned.
  • Examples: Provide cURL examples for requests and valid JSON blocks for responses.
  • Error handling: Document standard HTTP status codes and Qmova-specific error codes.
  • Constraints: Clearly state rate limits and pagination mechanisms.

15. Accessibility

Qmova documentation must be accessible to all users.

  • Headings: Ensure meaningful, sequential heading structures for screen readers.
  • Links: Use descriptive link text. Never use "Click here." Instead, use "View the API Reference."
  • Tables: Ensure tables have clear header rows. Avoid overly complex nested tables.
  • Images: Any image added must include descriptive alt text.
  • Contrast & Formatting: Rely on the default typography engine. Do not inject custom inline styles or colors that may break dark mode contrast.

16. Documentation Review Checklist

Before publishing or merging a documentation PR, contributors must verify the following:

  • [ ] Canonical terminology is used consistently.
  • [ ] All internal and external links are valid and unbroken.
  • [ ] Frontmatter version and lastUpdated dates are bumped.
  • [ ] Tangential topics are linked via <RelatedDocs /> instead of duplicated.
  • [ ] No unsupported technical or legal claims are made.
  • [ ] Spelling, grammar, and voice have been checked.
  • [ ] Diagrams render correctly in dark mode and include text explanations.
  • [ ] Markdown linting passes (no broken JSX/MDX tags).