Template: concept article

A practical authoring template for writing a concept article — an information type answering 'What is it?' with definitions, context, principles, and examples.

Updated September 2026, 3 min read

View as Markdown

What is a Concept?

A Concept is an Information typingThe discipline of classifying content by its communicative purpose (concept, task, reference) rather than writing undifferentiated prose.View in glossary →, not merely a writing style or decorative introduction. Its purpose is to answer one central question: “What is it?”

A Concept article:

Builds understanding: It supplies the definitions, background, context, and mental models readers need before they can work with a system effectively.
Maps relationships: It explains how components, ideas, or architectural layers relate to one another.
Does not instruct: It normally does not give sequential, step-by-step procedural instructions (which belong in a task article).
Prepares for action: Readers typically turn to concept articles when onboarding, evaluating an approach, or diagnosing an unfamiliar system state before carrying out tasks.

When to use a Concept

Write a Concept article when the reader’s primary goal is to understand:

What something is: Defining a technology, pattern, or domain entity (e.g., “What is an idempotency key?”).
How it works conceptually: High-level mechanisms, workflows, or data lifecycles (e.g., “How Git handles snapshots vs. deltas”).
Why it exists: The rationale, business justification, or engineering problem it solves.
How concepts relate to each other: System boundaries, dependency hierarchies, or mental models.
Terminology and foundational principles: Establishing vocabulary and core constraints.

Managing content boundaries

Keep the primary information type clear. A Concept article can include a small code snippet, configuration excerpt, or diagram to anchor an abstract principle. However, supporting material should not overwhelm the primary intent:

Brief illustration is welcome: A short snippet demonstrating a concept in action reinforces understanding.
Substantial procedures belong in a Task: If you find yourself writing sequential, multi-step instructions (“How do I configure X?”), move them to a Task article and link to it.
Exhaustive parameters belong in a Reference: If you find yourself compiling a comprehensive catalog of configuration options (“What are the parameters of X?”), move them to a Reference article and link to it.

Keeping the primary reader intent focused ensures users arriving to understand an architectural principle aren’t bogged down by exhaustive catalogs, while users trying to complete an urgent procedure aren’t forced to parse through background theory.

Recommended structure

The structure below is a practical authoring template for lightweight MarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary →/Astro workflows, applying the concept information-typing principle without DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → schemas or DTD (Document Type Definition)The oldest XML schema language: it declares which elements and attributes a document may contain, and in what order. DITA XML is distributed with DTDs as well as XSD schemas.View in glossary → validation. It organizes content logically from immediate definition to concrete demonstration:

Definition: Plain-language definition answering “What is it?” in one or two sentences.
Context (Why it matters): The practical consequence - what breaks, costs more, or fails without understanding this concept.
How it works (Key principles): The core ideas or mechanics that constitute the concept.
Key characteristics (Trade-offs): Boundaries, constraints, or alternatives when a deliberate choice is involved.
Examples: At least one concrete, real-world example illustrating the concept in practice.
Related concepts: Contextual links to parent, sibling, or downstream task TopicThe smallest autonomous, titled unit of information in DITA XML, typed as concept, task, or reference and assembled into documents via ditamaps.View in glossary →.

---
title: "<Concept name>"
description: "<One sentence: what the reader will understand after reading this>"
contentType: concept
---

## Definition

<One or two sentences defining the concept in plain language. A reader
skimming only this paragraph should walk away with a correct, if
incomplete, understanding.>

## Why it matters

<The consequence of understanding — or not understanding — this concept.
What breaks, costs more, or gets confusing without it?>

## Key principles

<The two to four ideas that make up the concept. A bulleted list or a
short table both work well here.>

## Examples

<At least one concrete example. Abstract concepts without an example
are the single most common cause of reader confusion.>

## Trade-offs

<Optional. Include only if the concept involves a real choice — when
would someone deliberately choose NOT to apply this concept?>

## Related concepts

- [<Related concept 1>](<link>)
- [<Related concept 2>](<link>)
- [<Downstream task>](<link>)

When to skip a section

Trade-offs: Omit entirely if no genuine dilemma exists, rather than inventing an artificial trade-off.
Why it matters: If the concept is straightforward and its value is completely self-evident from the definition, merge the two.
Never skip Definition or Examples: A concept topic without a clear definition leaves the reader guessing; a concept topic without a concrete example remains abstract and ungrounded.