> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cognite documentation style and voice

> Essential style considerations and voice principles for creating consistent, user-focused technical documentation across Cognite products

We follow the guidance in the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) for our technical documentation. This article covers the most important points from that comprehensive resource. The guidelines apply whether you're creating new documentation or updating existing content.

These rules are encoded for agents in **`rules/cognite-styleguide.md`** (canonical) and summarized here for human readers. Cursor and Claude Code auto-load the styleguide when editing MDX via thin rule wrappers; **`AGENTS.md`** at the repo root routes agents to skills and rules.

## Quick start checklist

<Tip>
  **Always do these things:**

  * Write in **American English**.

  * Check **spelling and grammar** in your articles, even if you need to copy and paste into a different editor.

  * Use a **casual and friendly** voice —l ike you're talking to another person one-on-one.

  * Write **simple sentences** that readers can quickly understand and act upon.
</Tip>

## Core writing principles

We aspire to follow these core principles when writing technical content for Cognite products:

<AccordionGroup>
  <Accordion title="Focus on the intent" defaultOpen={true}>
    * Customers have a **specific purpose** when they consult our documentation. Before writing, clearly determine [who the customer is](/cogdocs/reference/cogdocs-metadata#audience-metadata) and what they're trying to accomplish.

    * Write your article to help the customer **complete that specific task** successfully.
  </Accordion>

  <Accordion title="Use everyday words" defaultOpen={true}>
    * Try to use **natural language** — the words your customers actually use.

    * Be **less formal** but not less technical.

    * Provide **examples** that explain new concepts clearly and make them accessible to your audience.
  </Accordion>

  <Accordion title="Write concisely" defaultOpen={true}>
    * **Don't waste words.** Be affirmative and avoid extra words or excessive qualifiers.

    * Keep sentences **short and focused**. If a task has a qualifier, place it at the beginning of the sentence or paragraph.

    * Minimize the number of notes and use **screenshots** when they can replace lengthy explanations.
  </Accordion>

  <Accordion title="Make your article easy to scan" defaultOpen={true}>
    * Put the **most important information** first.
    * Use sections to **break long procedures** into manageable groups of steps.
    * Procedures with more than **12 steps** are probably too long and should be broken down further.
    * Use **screenshots** when they add clarity to the instructions.
  </Accordion>

  <Accordion title="Show empathy" defaultOpen={true}>
    * Use a **supportive tone** throughout your content and keep disclaimers to a minimum.

    * Honestly **acknowledge** areas that might frustrate customers.

    * **Focus on what matters to customers** rather than giving purely technical lectures.
  </Accordion>

  <Accordion title="Write for an international audience" defaultOpen={true}>
    * **Include the "small words"**. Words that we consider small and unimportant in English because they're understood from context (such as "a," "the," "that," and "is") are crucial for translation. Include them.

    * Use **active verbs** instead of nominalizations. Nominalizations are verbs or adjectives turned into nouns, often ending in -ion, -ment, or -ness.

    * **Avoid stacked modifiers**. Multiple nouns or adjectives grouped together create ambiguity about relationships between words.

    * Use **gender-neutral words**. Some languages have gender rules that don’t translate directly.

    * **Avoid slang, jokes, or culturally specific examples**. Use language that translates well.
  </Accordion>
</AccordionGroup>

## Reference resources

For comprehensive style guidance beyond this quick reference:

<CardGroup cols={3}>
  <Card title="Microsoft Style Guide" icon="microsoft" href="https://learn.microsoft.com/en-us/style-guide/welcome/">
    Complete style reference covering comprehensive writing guidelines for
    technical content
  </Card>

  <Card title="Content quality checklist" icon="check" href="/cogdocs/reference/cogdocs-quality-checklist">
    Checklist for ensuring your content meets quality standards.
  </Card>

  <Card title="Cognite terminology" icon="list" href="/cogdocs/reference/cogdocs-glossary">
    Internal terminology reference for consistent product and feature naming.
  </Card>
</CardGroup>