Template: task article

Information type:Task•"How do I do it?"

Step-by-step procedural workflow toward a verifiable outcome

Template

This is a starting point to copy and adapt, not a worked example. For a filled-in version, see the example docs-as-code workflow. To learn how tasks fit into information architecture, read Information types.

Use this structure when the reader’s primary intent is to do something with a concrete, verifiable outcome. Its steps and troubleshooting table apply two of the principles listed under Minimalism tested and stated as principles in the site history: an action-oriented approach, and support for error recognition and recovery.

Keep the primary information typeInformation typingThe discipline of classifying content by its communicative purpose (concept, task, reference) rather than writing undifferentiated prose.View in glossary → clear: a task article may include a sentence or two of conceptual context in its objective or prerequisites to explain why a step matters, but substantial architectural explanations belong in a dedicated concept article, and exhaustive parameter catalogs belong in a reference article.

The structure below is a practical authoring template for lightweight MarkdownMarkdownA 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 task information-typing principle without DITA XMLDITA 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 DTDDTD (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:

---
title: "<Verb-first task title, e.g. 'Configure X' or 'Migrate Y to Z'>"
description: "<One sentence: what the reader accomplishes>"
contentType: task
---

## Objective

<One sentence: what the reader will have working/done by the end.>

## Prerequisites

- <Required access, tool, or prior knowledge>
- <Required access, tool, or prior knowledge>

<Omit this section entirely if there truly are none — don't pad it
with "a computer" or other non-prerequisites.>

## Estimated time

<Only include if you can back it with a real number — a word count
divided by reading speed, or an actual timed run-through. Never guess.>

## Steps

1. <Action. Keep each step to one action a reader can complete
   before moving on.>
2. <Action.>
3. <Action.>

## Expected result

<What the reader should see if the steps worked. Concrete and
verifiable — a screenshot, a command output, a URL that now resolves.>

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| <What goes wrong> | <Why> | <What to do> |

<Omit if you don't have real failure modes to document — a fabricated
troubleshooting table is worse than none.>

## Related resources

- [<Related article 1>](<link>)
- [<Related article 2>](<link>)

When to skip a section

• Estimated time: only if you have a real basis for the number (see above).
• Troubleshooting: only document failure modes you’ve actually seen or can reason about concretely - this table degrades fast when padded with guesses.
• Never skip Objective, Steps, or Expected result - a task article without a verifiable outcome isn’t a task article.