Conceptual articles

What Is a Conceptual Article?

A conceptual article answers the question "What is X?" or "How does X work?" It builds understanding rather than guiding action. Readers turn to conceptual articles when they want to understand a feature, system, or idea before deciding whether or how to use it.

Conceptual articles are the "why" and "what" of your documentation. They complement how-to articles (the "how") and reference articles (the "what, exhaustively"). Every major feature or system in your knowledge base should have a conceptual article or section. See the Conceptual Articles section of the Five Core Content Types guide for how this type relates to the other four; this article is the fuller treatment of that entry.

When to write a conceptual article: when a reader needs to understand what something is, how it works at a high level, when to use it, or how it fits into the broader system — before they start doing anything.

Structure

Title

Use a noun phrase that names the concept. Avoid gerunds and imperative verbs.

Workspaces
Article versioning
How role-based access control works

Opening definition (1–3 sentences)

Define the concept clearly in the first sentence. Avoid starting with "This article explains..." State what the thing is, not what the article does.

Example: "Workspaces are isolated environments within a project where teams can work on separate content streams without interfering with each other. Each workspace can have its own set of articles, categories, and publishing settings."

Body sections

Cover the concept from the reader's perspective. Use H2 headings to organize the content. Typical sections for a conceptual article include:

How it works — describe the mechanics or behavior of the feature.
Key components — if the concept has named parts, describe each one briefly.
When to use it — describe the use cases that the concept supports.
Limitations or constraints — be honest about what the feature does not do or when it is not appropriate.
How it relates to other features — briefly explain how this concept connects to others the reader may know.

Not all sections are required for every article. Include what is genuinely useful. An article with three well-written sections is better than one with six that add no value — treat this list as a menu, not a mandatory checklist.

Length

A conceptual article typically works well between 400 and 1,200 words, per the Depth Versus Breadth guidance in the Structuring a Knowledge Base guide. If a concept genuinely needs more room than that to be understood clearly, consider whether it's actually two related concepts that deserve separate articles, cross-linked to each other.

Template

[Title — noun phrase]

[1–3 sentence definition of the concept]

## How it works
[Describe the mechanics, behavior, or logic of the feature]

## Key components
[Describe the parts of the concept if it has named sub-elements]
- **[Component 1]**: [Description]
- **[Component 2]**: [Description]

## When to use [concept]
[Describe the use cases where this concept is relevant]

## Limitations
[Describe what this feature does not do or constraints the reader should know]

## Related articles
- [How-to article 1]
- [Reference article]

What Makes a Good Conceptual Article

It builds a mental model. After reading it, the reader should understand how the feature fits into their workflow, not just what it is called.
It uses analogies sparingly and carefully. An analogy can illuminate a complex concept — but only if the analogy itself is universally understood. Test analogies against your global audience the same way you'd test any example or idiom; see the Avoid Culturally Loaded Metaphors and Examples section of the Cultural Considerations in Global Documentation guide for the underlying reasoning and more examples of analogies that don't travel well.
It does not duplicate how-to content. A conceptual article should not include step-by-step instructions. If you find yourself writing steps, link to the how-to article instead — see the Writing How-To Articles guide.
It stays at the right level of detail. A conceptual article gives enough detail to build understanding — not every edge case or configuration option. Save exhaustive detail for reference articles.
It defines jargon immediately, rather than assuming it. See the Explain Jargon When You Must Use It section of the Plain Language Principles guide for the inline-definition technique — conceptual articles are exactly where a reader is likely to encounter a term for the first time.
It uses diagrams where they genuinely clarify structure or relationships. See the Diagrams and Illustrations section of the Images, Screenshots, and Video guide for when a diagram is worth the investment and how to keep it simple.

Tone

Explanatory and clear. The reader is curious or planning — they are not in the middle of a task. You have slightly more room to explain and contextualize than in a how-to. Avoid jargon unless you immediately define it. Use diagrams and tables where they genuinely clarify the concept.

Self-Audit Checklist

Before publishing, check the conceptual article against these questions:

Does the title use a noun phrase, not a gerund or imperative verb?
Does the opening sentence define the concept directly, without "This article explains..."?
Are only the body sections that add genuine value included, rather than every possible section?
Is the article within the 400–1,200 word range, or split into separate articles if it genuinely needs more?
Is every analogy tested against a global audience, with no culturally specific reference points?
Is the article free of step-by-step instructions, with a link to the relevant how-to article instead?
Is every technical term defined on first use?
Would a reader walk away with a working mental model of how the feature fits into their workflow, not just its name?
Does the article end with related how-to and reference links?

Documentation Index