Skip to main content

Style Guide

This guide defines the standards for writing C_AI Platform documentation.

Terminology rules​

Forbidden terms​

The following terms must never appear in documentation:

ForbiddenReason
CMLegacy internal terminology
Compliance ManagerLegacy product name

The linter will fail if these terms are detected.

Required terminology​

Use these terms consistently:

TermUsage
End UserAny person using the platform to submit or view compliance data
Portal UserA user accessing the platform through the web interface
AdminAdministrative user with elevated permissions
TenantOrganization-level isolation boundary
PackConfiguration bundle for a specific use case

Voice and tone​

Be direct​

Write in active voice. Address the reader directly.

❌ The document should be uploaded by the user.
✅ Upload your document.

Be concise​

Avoid unnecessary words.

❌ In order to complete the process of uploading a document...
✅ To upload a document...

Be helpful​

Anticipate questions and provide context.

❌ Click Submit.
✅ Click Submit. Large files may take longer to upload.

Formatting standards​

Headings​

  • Use sentence case: "Getting started" not "Getting Started"
  • Use H2 (##) for major sections
  • Use H3 (###) for subsections
  • Do not skip heading levels

Code blocks​

Always specify the language:

```bash
yarn install
```

```typescript
const result = await api.getHealth();
```

Admonitions​

Use Docusaurus admonitions for callouts:

:::note
Helpful information that adds context.
:::

:::tip
Best practices or shortcuts.
:::

:::warning
Important cautions or potential issues.
:::

:::danger
Critical warnings about destructive actions.
:::

Tables​

Use tables for structured comparisons:

| Feature | Free | Pro |
|---------|------|-----|
| Storage | 1 GB | 10 GB |
| Users | 5 | Unlimited |

What "good" looks like​

A good documentation page:

  1. Starts with context: Explains what the page covers and who it is for
  2. Provides clear structure: Uses headings and lists for scanability
  3. Includes examples: Shows real inputs and outputs
  4. Addresses errors: Documents common issues and solutions
  5. Links to related content: Connects to relevant guides and concepts

Quality checks​

Before submitting documentation:

cd docs-site
yarn lint

This runs:

  • Terminology checks (no forbidden terms)
  • Markdown linting
  • Spell checking
  • Build verification