Skip to main content
We follow the guidance in the Microsoft Style Guide 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

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.

​
Core writing principles

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

Focus on the intent

  • Customers have a specific purpose when they consult our documentation. Before writing, clearly determine who the customer is and what they’re trying to accomplish.
  • Write your article to help the customer complete that specific task successfully.

Use everyday words

  • 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.

Write concisely

  • 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.

Make your article easy to scan

  • 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.

Show empathy

  • 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.

Write for an international audience

  • 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.

​
Reference resources

For comprehensive style guidance beyond this quick reference:

Microsoft Style Guide

Complete style reference covering comprehensive writing guidelines for technical content

Content quality checklist

Checklist for ensuring your content meets quality standards.

Cognite terminology

Internal terminology reference for consistent product and feature naming.
Last modified on August 27, 2026