What Is a How-To Article?
A how-to article answers the question "How do I accomplish X?" It is task-oriented: the reader arrives with a specific goal and leaves with the steps needed to achieve it. How-to articles are the most common content type in a knowledge base. They differ from tutorials in that they assume the reader already understands the context — they just need the procedure. See the How-to Guides section of the Five Core Content Types guide for how this type relates to the other four.
When to write a how-to: when a user needs to perform a specific, bounded task — "How to add a new user," "How to configure SSO," "How to export articles as a ZIP file."
How this relates to the Writing Procedures guide: a how-to article is the primary place the general procedure-writing rules apply. This article covers the how-to-specific structure — title conventions, intro, prerequisites, result, and next steps — and cross-references Writing Procedures for the mechanics of writing the steps themselves (one action per step, imperative verbs, bolding UI elements, stating results, sub-steps). Read both together when writing a how-to article.
Structure
Title
Start with an imperative verb. The title should complete the sentence "How to ___." See the Title Formats by Content Type table in the Headings and Titles guide, which lists this same convention for how-to guides — this section is the fuller version of that entry.
- Add a new user
- Configure single sign-on (SSO)
- Export your knowledge base as a ZIP file
Avoid titles that start with gerunds ("Adding a new user") or nouns ("User addition"). Imperative titles are cleaner, more scannable, and consistent.
Introductory sentence (1–2 sentences)
State what the article helps the reader do and any significant prerequisite or constraint. Keep it to one or two sentences. Do not restate the title.
Example: "You can invite new team members to your knowledge base portal from the Users & groups settings. You need Owner or Admin access to complete this task."
Prerequisites (optional)
List what the reader needs before starting. Use a short bulleted list. Omit this section if there are no prerequisites.
Steps
Write steps as a numbered list, following the step-writing rules in the Writing Procedures guide: one action per step, imperative verbs ("Select," "Enter," "Click," "Toggle"), bolded UI element names, and stated results where the outcome isn't obvious.
A few points specific to how-to articles:
- If a step has sub-steps or a decision branch, use a nested list sparingly, per the Sub-Steps and Branching Procedures guidance in Writing Procedures.
- Include a screenshot where it resolves genuine ambiguity, per the Screenshots Within a Procedure section of that same guide — not by default on every step.
Aim for 3–12 steps. This is a tighter ceiling than the general procedure guidance (which allows up to 10 steps before recommending phased H3 headings, and treats longer procedures as a case-by-case judgment call). The tighter number here reflects the how-to content type's defining constraint: a how-to article should cover exactly one bounded task, so a procedure that's outgrowing 12 steps is usually a sign the task itself has stopped being single and bounded — split it into sub-task articles rather than phasing one long article, since each sub-task likely deserves its own how-to title, intro, and result statement.
Result (optional)
After the final step, add a brief statement describing the outcome: "The user receives an invitation email and appears in the Users list with a Pending status."
Next steps (optional)
Offer 1–3 links to related tasks that a reader is likely to want after completing this one.
Template
[Title — imperative verb phrase]
[1–2 sentence intro stating what this article covers and any key prerequisite]
## Before you begin
- [Prerequisite 1]
- [Prerequisite 2]
## Steps
1. [Action]. [Expected result if not obvious].
2. [Action].
3. [Action].
- [Sub-step if needed]
4. [Action].
[Brief statement of the outcome after the final step]
## Next steps
- [Related task 1]
- [Related task 2]
Common Mistakes to Avoid
- Explaining why at length. How-to articles are for doing, not for understanding. Link to a conceptual article if the reader needs background.
- Combining multiple tasks. "How to add and manage users" is two articles. Keep each how-to focused on one task.
- Vague step language. "Configure your settings as needed" is not a step. Be specific about what the reader should do.
- Missing UI context. Always tell the reader where they are navigating: "In the left navigation bar, select Settings."
- No result confirmation. After a consequential step, confirm what the reader should see.
Tone
Direct and efficient. The reader is busy. Use "you" throughout. Avoid "please" in step instructions — it adds no information and slows the reader down. Save warmth for the intro and outro.
Self-Audit Checklist
Before publishing, check the how-to article against these questions:
- Does the title start with an imperative verb, completing "How to ___"?
- Is the intro one to two sentences, stating the task and any key prerequisite without restating the title?
- Are prerequisites listed only if they exist, and omitted otherwise?
- Does every step follow the one-action-per-step and imperative-verb rules from Writing Procedures?
- Are UI element names bolded, and are results stated after any step with a non-obvious outcome?
- Is the procedure between 3 and 12 steps, with anything longer split into separate how-to articles for each sub-task?
- Does the article end with a result statement and, where relevant, one to three next-step links?
- Is the tone direct and efficient, free of "please" in step instructions and free of lengthy explanation better suited to a conceptual article?
- Does the article cover exactly one bounded task, not two combined into one?