Template: concept article

Information type:Concept•"What is it?"

Understanding, background, definitions, and mental models

Template

This is a starting point to copy and adapt, not a worked example. For a complete annotated illustration of this pattern, see Example: a well-structured Markdown page. To understand where Concept fits into documentation architecture, read Information types.

What is a Concept?

A Concept is an information type, 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 Markdown/Astro workflows, applying the concept information-typing principle without DITA XML schemas or DTD validation. It organizes content logically from immediate definition to concrete demonstration:

1. Definition: Plain-language definition answering “What is it?” in one or two sentences.
2. Context (Why it matters): The practical consequence - what breaks, costs more, or fails without understanding this concept.
3. How it works (Key principles): The core ideas or mechanics that constitute the concept.
4. Key characteristics (Trade-offs): Boundaries, constraints, or alternatives when a deliberate choice is involved.
5. Examples: At least one concrete, real-world example illustrating the concept in practice.
6. Related concepts: Contextual links to parent, sibling, or downstream task topics.

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