Documentation content templates

These templates are starting points, one for each of the four content types. They are written for Reed: frontmatter carries only title and description, and every component comes from the fixed catalog.

To use one:

1. Copy the template that matches the page’s type into a new .mdx file.
2. Replace every bracketed placeholder with real content.
3. Add or reorder sections where your subject needs it.
4. Delete every section that does not apply. An empty “Troubleshooting” heading is worse than none.

The templates use components sparingly on purpose. Most of a good page is headings, prose, lists and fenced code, which read equally well in the rendered page, in a diff and in the page’s markdown mirror. Each component below is there because it does something markdown cannot.

Three rules hold for every template:

• No H1 in the body. The title becomes the H1. Headings start at ## and never skip a level, or reed check reports DS-A02.
• Fences stay at the top level. Keep fenced code out of Step, Tab, Card and Accordion. A nested fence only parses when it and the tags around it sit on their own lines, with blank lines between, so the top level is the safer habit. See MDX pitfalls.
• Links carry the base. Reed does not rewrite links in prose. On a site with base: "/docs", a link to another page is written /docs/<page-id>, in markdown and in every href.

How-to guide template

Use a how-to guide when the reader already knows the product and needs to finish one specific task. It goes straight to the solution.

mdx

---
title: "[Verb] [object], e.g. Rotate an API key"
description: "[Do the task] to [reach the outcome]."
---

One or two sentences on what this guide gets done, and when you would need it.

## Prerequisites

List only what the task truly requires:

- [Setup or configuration that must already exist]
- [Permissions the reader needs]
- [Related features that must be configured first]

## [Name the task as an action]

1. Open [location] and go to [specific place].
2. Select [button or option].
3. Enter [required value].
4. Select [confirmation button].

Then run the command, or edit the file, that completes the change:

```bash
[command the reader can copy and adapt]
```

<Tip>
  [The one mistake readers most often make here, and how to avoid it.]
</Tip>

## Verify the result

[Only when success is not obvious: what the reader should see, and where.]

## Troubleshooting

- **[Symptom as the reader would describe it]:** [Cause and fix.]
- **[Another symptom]:** [Cause and fix.]

## Related tasks

- [Title of a related how-to guide] — [when to read it instead]
- [Title of the next logical task]

The list keeps the steps and the fence stays below it. If every list item ended up holding its own code block, reed check would suggest Steps with DS-D04. Since these templates keep fences out of Step, the better fix is usually one ## heading per step.

Tutorial template

Use a tutorial to teach a newcomer through hands-on practice. It walks through one complete, working example with a clear outcome.

mdx

---
title: "[Build or do] [specific outcome]"
description: "Learn to [outcome] by [method], step by step."
---

Say what the reader will have built by the end, what they will be able to do next, and
roughly how long it takes.

## Before you start

- [Knowledge the reader needs]
- [Tools, accounts or access]

## 1. [First action]

[Exactly what to do. No alternatives.]

```bash
[first command]
```

[What that just did, in one or two sentences, and why it matters.]

## 2. [Second action]

[The next step, building on the first.]

```bash
[second command]
```

<Check>
  [A milestone the reader can see: "Your site now builds without errors."]
</Check>

## 3. [Third action]

[Keep each step a concrete action, not theory. Make the choice for the reader.]

## Next steps

You [one sentence summarizing what was built]. From here:

- [A how-to guide for the most common next task]
- [An explanation page for readers who want to know how it works]
- [The reference page they will come back to]

Numbered ## headings do the job Steps would do here, and they keep each command in a top-level fence. The stages also appear in the table of contents. Reed’s own Quickstart uses this shape.

Use one Check at a real milestone, not after every step. Three or more callouts in a row draw a DS-D06 suggestion, and a page full of them has no emphasis left.

Explanation template

Use an explanation when the reader needs to understand a concept, a design decision or how a complex feature works. It builds understanding instead of giving instructions.

mdx

---
title: "How [concept] works"
description: "What [concept] is, why it exists, and where it fits in [product]."
---

Open with what this page explains and why a reader would care.

Define the concept in plain language: what it is, what it does, why it exists. Compare it
to something the reader already knows when a comparison genuinely helps.

## How [concept] works

Describe the mechanism, the architecture or the process, one idea per section.

<Frame caption="[What the diagram shows, in one sentence.]">
  ![[Describe the diagram for a reader who cannot see it]](https://example.com/diagram.png)
</Frame>

## Why [the design decision]

Say why it works this way. Name the tradeoffs, the alternatives that were considered, and
the constraints that ruled them out.

## When to use [concept]

- **[Situation]:** why this is the right approach there.
- **[Another situation]:** why it fits.
- **Not for [situation]:** what to use instead.

## How it relates to [neighboring feature]

Connect the concept to the rest of the system and to the reader's workflow.

## Common misconceptions

Correct the misunderstandings you actually hear, one at a time.

## Further reading

- [A how-to guide that puts this concept to work]
- [The reference page for its settings]

Replace the image URL with your own. The alt text is not optional: an image without it is DS-A01. Write alt text that says what the diagram shows, not “diagram”.

Reference template

Use reference when the reader needs to look up exact details. It favors accuracy, consistency and scannability over everything else.

mdx

---
title: "[Feature or API name] reference"
description: "Every [parameter, option and field] of [feature or API], with types and defaults."
---

One sentence on what this feature or endpoint does.

## Parameters

<ParamField name="[name]" type="string" required>
  [What it controls. One or two sentences.]
</ParamField>

<ParamField name="[name]" type="number" default="[default]">
  [What it controls, and what happens at the default.]
</ParamField>

<ParamField name="[name]" type="boolean" default="false">
  [What turning it on changes.]
</ParamField>

<ParamField name="[name]" type='"[option-a]" | "[option-b]"'>
  [What each option does.]
</ParamField>

## Response

<ResponseField name="[field]" type="string" required>
  [What the field contains.]
</ResponseField>

<ResponseField name="[field]" type="number">
  [What the field contains, and when it is absent.]
</ResponseField>

```json
{
  "[field]": "[value]",
  "[field]": 123
}
```

## Examples

### Minimal request

```bash
[the smallest call that works]
```

### Full request

```bash
[a call that sets most of the parameters above]
```

## Limits

- [Rate limits, size limits, maximum values]
- [Edge cases and what happens at them]

## Related references

- [Title of a related reference page]

ParamField takes the parameter’s name in name, and ResponseField requires both name and type. Use in on a ParamField to say where a parameter goes — query, path, header, body or cookie. The full prop list is in API reference components.

The examples sit under their own headings, so their fences are not adjacent. If you show one call in several languages, put the fences in a CodeGroup and title each with its language. Adjacent fences in different languages outside one draw a DS-D03 suggestion to use CodeGroup — see Format code.

If you document an HTTP API from an OpenAPI spec, you may not need this template at all: Reed renders endpoint pages from the spec with its own generated layout. ParamField and ResponseField are for hand-written API pages like this one.

Related pages

Documentation content types

Decide which template a page needs.

How to write technical documentation

The sentence-level rules the templates assume.

Using components

When a component earns its place, and when it does not.

Pages

Frontmatter, page ids and links.