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

# Understanding the content information architecture

> Learn how documentation is organized in the repository: folder layout, the content model from collections through articles, and Mintlify components for a consistent reader experience.

Information architecture is the backbone of effective documentation. This guide explains how content is organized and the rationale behind its structure. Understanding this architecture will help you create and maintain documentation efficiently.

## Repository structure

The documentation repository is structured for **clarity** and **scalability**. The main files and folders are:

| Path               | Purpose                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docs.json`        | Configuration file that defines site-wide settings, navigation, and metadata.                                                                            |
| `api‑reference/`   | API reference documentation, typically auto-generated or manually curated for each endpoint.                                                             |
| `cdf/`, `dev/`     | Core documentation for CDF and developers documentation. Contains: `index.mdx` (map/overview), `concepts/`, `reference/`, `guides/`, `troubleshooting/`. |
| `de/`, `fr/`, etc. | Language-specific folders with translated content, mirroring the English structure.                                                                      |
| `images/`          | Centralized location for images.                                                                                                                         |
| `snippets/`        | Reusable text snippets. See [Content reuse](#content-reuse).                                                                                             |

When adding new content, always update the relevant map topic and make sure your files follow the established folder structure.

## Content model

Our content model outlines the purpose of each [**content type**](#content-types) we create and what to include when writing or updating an article. We use this model to ensure that our content consistently conveys the information people need to reach their goals with Cognite products.

The content types ensure a consistent user experience, and any content type can be used with any **product feature** or **audience**.

Consistency helps people develop mental models of the documentation and understand how to find information when they return to the site. It also makes maintaining and updating content more efficient.

### Content structure

Organizing content involves finding a **balance** between creating specific groups that help users locate what they need and limiting the number of hierarchy layers they must navigate. Too **deep** or **wide** hierarchies can make it hard for users to access the right information.

We use these hierarchical levels:

<Frame caption="Content hierarchy levels">
  ```mermaid actions={false} theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  %%{init: {"theme":"base","themeVariables":{"primaryColor":"#E4E6E8","primaryTextColor":"#191B1D","primaryBorderColor":"#5E666D","lineColor":"#5E666D","secondaryColor":"#DFE5FC","tertiaryColor":"#FFFFFF"}}}%%
  graph TD
  A[Collection]
  A --> B[Categories]
  B --> C[Map topics]
  C --> D[Articles]
  B --> E[Articles]
  A --> F[Articles]
  A --> G[Map topics]
  G --> H[Articles]
  style A fill:#2F55EA,stroke:#2F55EA,color:#fff
  style B fill:#14735E,stroke:#14735E,color:#fff
  style C fill:#9940A6,stroke:#9940A6,color:#fff
  style G fill:#9940A6,stroke:#9940A6,color:#fff
  style D fill:#AD4506,stroke:#AD4506,color:#fff
  style E fill:#AD4506,stroke:#AD4506,color:#fff
  style F fill:#AD4506,stroke:#AD4506,color:#fff
  style H fill:#AD4506,stroke:#AD4506,color:#fff
  ```
</Frame>

The diagram shows **collections** at the top of the hierarchy; **categories** and **map topics** sit below them, with **articles** linked at several levels so the same article type can appear where readers need it.

#### Collection

Collections are the top-level of the hierarchy and are organized around a **workspace**, **role**, or core **workflow**, such as "Industrial tools," "Admin," or "Data integration." All collections appear on the site homepage and in the topbar.

Collections can include a mix of categories, map topics, or articles.

#### Category

A category is organized around a set of tasks or a feature, for example, "Field operations" or "Data modeling".

Within a category, include articles or map topics to subdivide content into more specific tasks.

Category **titles** are task-based (begin with a gerund), and their **intros** describe the big-picture purpose or goal of using the feature.

#### Map topic

Map topics group articles in a category by specific workflows or subtopics. We typically use Mintlify [cards and columns](#cards-and-columns) to build map topics.

Include at least two articles in each map topic. If a map topic has more than eight, consider splitting it into more specific map topics.

Map topic **titles** are task-based (begin with a gerund).

#### Article

Articles are the basic content units. Each article uses one of the [**content types**](#content-types) described below. Each content type has a different purpose and structure, but they all share standard elements, like intros and callouts, to create a consistent experience.

### Content types

We use seven content types — concept, reference, procedure, quickstart, tutorial, troubleshooting, and **map** — each with a defined purpose, structure, and title pattern. Release and changelog content uses `reference` or `concept`, not a separate type. For the decision guide and per-type requirements, see [Choosing your content type](/cogdocs/concepts/cogdocs-content-types). Voice, Mintlify components, and accessibility standards: **`rules/cognite-styleguide.md`** in the repo (see [Style and voice](/cogdocs/concepts/cogdocs-style-guide) for a human summary).

<Note>
  Across the site, we often collectively refer to **procedural** content, **tutorials**, and **quickstarts** as "guides."
</Note>

### Content order

We organize content consistently across categories, map topics, and articles. From broad to specific, use this order:

* Conceptual content
* Reference content
* Procedural content
* Troubleshooting information

### Content reuse

Use reusable **snippets** and variables to include the same content in multiple places. Avoid reusing large sections of articles unless there’s a specific reason.

Store reusable texts in the `snippets` folder. See [Reusable snippets (external)](https://mintlify.com/docs/reusable-snippets#creating-a-custom-snippet) for more information on how to create and use snippets.

## Content components

We use Mintlify components to create a consistent user experience across all content. Components are reusable UI elements that provide structured ways to display information, organize content, and create interactive elements. Each component has specific properties and configuration options.

The sections below describe when to use the most common components.

### Accordions

Accordions help create cleaner, more scannable documentation by allowing users to focus on what's relevant to them while keeping additional information easily accessible.

Example use cases include glossaries, troubleshooting information, or additional information that might interrupt flow.

Learn more: [Mintlify accordion component (external)](https://mintlify.com/docs/components/accordions)

### Callouts

Callouts draw attention to important information and provide visual cues to readers about the type of content they contain.

Readers often skip callouts. Prefer including critical information directly in the article text. If you use callouts, limit them to one or two per article and avoid placing multiple callouts next to each other.

Callout types:

* **Info**: Neutral contextual information or background details.
* **Note**: Supplementary information that supports the main content.
* **Tip**: Helpful suggestions, best practices, or pro tips.
* **Check**: Positive confirmations or success indicators.
* **Warning**: Important cautions or critical information about potential issues.
* **Danger**: Critical warnings about destructive actions or serious issues.

Learn more: [Mintlify callouts component (external)](https://mintlify.com/docs/components/callouts)

### Cards and columns

We use **cards** and **columns** primarily to build landing pages and [map topics](#map-topic) to provide [collection](#collection) and [category](#category) overviews.

Learn more: [Mintlify card component (external)](https://mintlify.com/docs/components/cards), [Mintlify columns component (external)](https://mintlify.com/docs/components/columns)

### CodeGroup

CodeGroup allows you to use a tabbed interface to display code examples in different programming languages or for different tools. CodeGroups can only contain code blocks.

Learn more: [Mintlify code group component (external)](https://mintlify.com/docs/components/code-groups)

### Frames

Use frames to **center** illustrations and screenshots and add a **caption** to them.

Don't use frames for inline images, or if you want images to fill the full width without centering.

While primarily used for images, frames can also wrap other components, for example **Mermaid diagrams**.

Learn more: [Mintlify frame component (external)](https://mintlify.com/docs/components/frames)

### Steps

Steps are a series of **sequential actions** that are part of a [procedure](/cogdocs/concepts/cogdocs-content-types#procedure), [tutorial](/cogdocs/concepts/cogdocs-content-types#tutorial), or [quickstart](/cogdocs/concepts/cogdocs-content-types#quickstart) article.

<Tabs>
  <Tab title="Do">
    * **Use numbered steps for sequential tasks**: When the order matters, use the Steps component to guide users through the process.
    * **Use the component for two or more steps**: Use the Steps component when you have two or more sequential actions. If you have only one step, use a numbered list instead.
    * **Use clear, action-oriented titles**: Begin step titles with verbs, for example, "Configure the API key," "Install dependencies," or "Test the connection."
    * **Provide context**: Always add explanations within steps, even if the title is self-explanatory.
    * **Define optional steps**: Show when a step is optional, for example, "Optional. Configure authentication."
  </Tab>

  <Tab title="Don't">
    * **Don't use steps for non-sequential information**: Use bulleted lists instead when the order doesn't matter.
    * **Don't use the component for single steps**: Use a single-step numbered list instead of the Steps component. However, you can use the Step component if it's visually better than a numbered list, for example, when the step is a single command with an example below.&#x20;
    * **Don't nest the component**: Don't nest the Steps component within another Steps component. Use a numbered list instead.
  </Tab>
</Tabs>

Learn more: [Mintlify steps component (external)](https://mintlify.com/docs/components/steps)

### Tabs

Organize related content in tabs that people can toggle between. Tabs can be useful for:

* Organizing platform-specific instructions (macOS, Windows, Linux).
* Showing different approaches to the same task.
* Separating beginner vs. advanced content.

Tabs can contain any type of content—text, components, images, code blocks, and more.

Learn more: [Mintlify tabs component (external)](https://mintlify.com/docs/components/tabs)

## Further reading

* [Choosing your content type](/cogdocs/concepts/cogdocs-content-types) — decision guide and per-type requirements
* [Metadata reference](/cogdocs/reference/cogdocs-metadata) — frontmatter fields and allowed values
* [Mintlify navigation (external)](https://mintlify.com/docs/organize/navigation) — tabs, groups, and sidebar structure