Choosing your content type

Content type is the most important metadata decision you make when writing an article. It determines the article’s structure, title pattern, required sections, and where it belongs in the information architecture. Choosing the wrong type leads to content that doesn’t serve users well regardless of how well it’s written.

​

How to choose

Start with the user’s intent when they arrive at the article: If you’re uncertain between two types, ask: is the user trying to understand, or trying to do? Concepts build mental models. Procedures drive actions. Most confusion happens at that boundary.

​

Content types in detail

Each type below answers a different reader question. Use these sections to confirm your choice from the table above, or to tell similar types apart. For every type you’ll find the intent it serves, how to title and structure the article, and what to avoid.

​

Concept

Answers: What is it? How does it work? Why does it exist? Concepts build understanding. They don’t include step-by-step instructions. A concept article about authentication explains what OAuth is and why Cognite uses it — not how to configure it. Title pattern: “Understanding X”, “About X”, “How X works”
Avoid: Numbered steps, imperative verbs as section headers, UI interaction details

​

Procedure

Answers: How do I do this specific task? Procedures drive a single, discrete action to completion. One procedure = one task. If a user needs to do two things, write two procedures and link them. Title pattern: Verb + object — “Configure X”, “Set up X”, “Enable X”
Required: Prerequisites, numbered steps, expected outcome

​

Reference

Answers: What are the allowed values / parameters / options? Reference articles are for lookup, not reading. Users arrive with a specific question (“what values does lifecycle accept?”) and leave once they have the answer. Optimise for scannability: tables, lists, and consistent structure over prose. Title pattern: “X reference”, “X values”, “X API”
Avoid: Long explanatory prose, step-by-step instructions

​

Tutorial

Answers: How do I build or accomplish something complex from start to finish? Tutorials teach through doing. Unlike procedures, they cover a complete workflow with multiple related tasks, explain the reasoning behind decisions, and are written in a conversational, expert-to-expert tone. They assume more time and intent from the reader. Title pattern: “Build X”, “Create X with Y”, “X end-to-end”
Required: Clear learning outcome, real-world project example, prerequisites

​

Quickstart

Answers: How do I get something working as fast as possible? Quickstarts are optimised for speed over depth. Cover only the minimum path to a meaningful result — 5 minutes or less. Link out to procedures and concepts rather than explaining inline. Every line of a quickstart should earn its place. Title pattern: “Get started with X”, “X in 5 minutes”
Required: Prerequisites, numbered steps, clear success state, next steps

​

Troubleshooting

Answers: Why isn’t this working? How do I fix it? Troubleshooting articles are symptom-first. The user arrives with a broken state and needs to diagnose and resolve it. Structure content around observable symptoms, not around system components. Title pattern: “Troubleshoot X”, “Fix X error”, “Resolve X issues”
Required: Symptom descriptions, diagnostic steps, resolution steps, escalation path

​

Map

A map is a navigation hub — it organises other articles, not content of its own. Use it as the landing page for a section or group when users need help choosing where to go next. Rule: When content-type is map, also set article-type: map. These are the only articles where that applies.
Avoid: Writing substantial content in a map — it belongs in the articles the map links to

​

Release notes and changelog

Answers: What changed in this release and what do I need to do? Release notes and changelogs help administrators plan upgrades in change-controlled environments and help end users prepare for new Cognite features. Writers collaborate with product managers, TPMs, and engineers to source, edit, and publish these updates. Workflow: Writers publish release updates through the same documentation repository and review process as other articles.

​

Common mistakes

Mixing types in one article. If an article explains a concept and provides step-by-step instructions, split it. Users in procedure mode skip concept content; users in concept mode get confused by steps. Writing procedures as concepts. “X allows you to configure Y by navigating to…” is a procedure written in concept language. If there are UI steps, use a procedure. Making every article a reference. Reference is for lookup. If users need to read and understand before acting, it’s a concept or procedure.

​

Further reading

• Metadata reference — all required frontmatter fields and allowed values
• Information architecture — how content types fit the broader content model
• Content quality checklist — quality criteria for each content type