Skip to main content

​
Concept template

Use this template for a concept (explanation) page: understanding-oriented content that answers “What is this?” and “Why does it work this way?”. This is the Explanation quadrant in dev-doc-types. A concept is not a how-to. If the reader wants to do something, write a how-to or tutorial. Concept pages are the single home for the “why” — define each concept once here, then link to it from task pages so explanation never leaks into steps.

​
When to use

  • Introducing an API or product area: “What is the Trigger Inbox API?”
  • Explaining a model or mechanism: “How leasing and visibility timeouts work”
  • Helping a reader decide whether something fits their use case

​
Always apply

Apply all Foundational skills as you write — writing standards, accessibility, formatting, code examples, terminology. See SKILLS-INDEX. Use code examples only where a short illustrative snippet aids understanding.

​
Template location

assets/template-concept.mdx — structure and placeholders only.

​
Required sections (in order)

SectionPurpose
Intro (no heading)One or two sentences defining the concept in plain language.
## What [X] isThe definition and mental model. Use an analogy if it helps (e.g. “like an SQS queue”).
## How [X] worksThe mechanism. Prefer a Mermaid diagram or a state table over prose.
## When to use [X]The scenarios it fits.
## When not to use [X]The honest limits and the alternative.
## RelatedLinks to the tutorials and how-tos that act on this concept.

​
Writing rules

  • Define, do not instruct. No numbered task steps. If you write “first, call…”, that belongs in a how-to.
  • One concept per page. If the title joins two ideas with “and”, split it.
  • Lead with a mental model. A concrete analogy (“an inbox is a pull-based queue, like SQS”) orients the reader fast.
  • Diagrams over prose for mechanisms. Use a mermaid block for flows, lifecycles, and state machines — agents can parse it and screenshots cannot.
  • Be honest about limits. State what the concept does not cover and link to where that lives.
  • No pronouns for technical objects across paragraphs — repeat the canonical name.

​
Naming

  • Noun-phrase title: “What is the Trigger Inbox API?”, “Message lifecycle and leasing”.
  • Avoid verb-led titles — those signal a how-to.

​
Frontmatter

Set only title and description (see formatting-guidelines).

​
Before you finish

Register the page in docs.json and update llms.txt (contribute-docs), then run review-before-done.