Skip to content
Redaction-technique.org

Template: task article

By Olivier Carrère, technical writer

View as Markdown

Use this structure when the reader’s primary intent is to do something with a concrete, verifiable outcome.

Keep the primary information type 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 Markdown/Astro workflows, applying the task information-typing principle without DITA XML schemas or DTD 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

Section titled “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.