Skip to main content

How-to help article guidelines

Writing guidelines for your how-to style articles.

Written by Asa MacLean

When a customer wants to know how to do something, they have a specific goal in mind. As such, how-to style articles should reflect that goal.

Before you start

To write a great how-to style article, you need to have the right preparation. Ensure you can check off everything on this list.

✅

I know what the reader’s goals are.

✅

I know all permission requirements.

✅

I know the shortest path to success.

✅

I know the obvious questions or pitfalls we need to address along the way.

✅

I know if this is part of a series or stand-alone.

Article structure

Title

Use action-oriented, imperative verbs to create confident, goal-driven titles that reflect the content of the article.

🔎 Example: Create a new user or Delete duplicate users
​
​

Other good verbs include Add, Edit, Delete, Archive, Move, or Update.

✅ Do

❌ Don't

Export a report to PDF

How to export a report to PDF

Archive a policy

To archive a policy

Update account details

Updating account details

Configure the user dashboard

User dashboard

Description

One sentence that gives context and uses second-person pronouns to make it personal. A description should not include important information or detail - that's what the solution is for.

🔎 Example: Steps to create and set up your new user in Access [Product].

✅ Do

❌ Don't

Export and download your reports to PDF documents.

Export a report to PDF.

Steps you can take to solve the ABC error.

Steps if there's an ABC error.

Add or view assets in your asset library.

Your asset library is where you store assets that you might use in campaigns, including images, videos, PDFs etc.

Article introduction

Give a confident overview of the process and reassure the reader they can do it. A couple of sentences is usually enough, you don't need to write paragraphs of text.

🔎 Example: You can use the new user wizard to easily add your new users to the system. Follow these simple steps to get started.
​

📌 Note: You can use 'To [action]' format for section introductions but not the main article introduction.

✅ Do

❌ Don't

You can quickly bulk update your employee's permissions using the update manager in the settings menu.

The settings menu has the update manager.

You can archive a document in three simple steps.

To archive a document...

Step-by-step instructions

Use clear, numbered steps starting with imperative verbs and include prerequisites if needed. Try and keep steps short and a uniform length where possible; you can add two simple actions on a single step but don't go above two.

🔎 Example: Click Menu, then click Settings.

✅ Do

❌ Don't

  1. Click Menu, then click Settings.

  2. Click Users, then click New User.

  1. Click Menus and then go to settings.

  2. Click Users.

  3. When here, click New Users.

  1. Select your user, then click Actions.

  2. Select the complete checkbox.

  3. Click Save.

  1. Select your user, then click Actions.

  2. Select the complete checkbox, then click Save.

  1. Click File, then click Customers.

  2. Select Complete, then click Save.

  1. Click File.

  2. Click Customers.

  3. Select Complete.

  4. Click Save.

Sections

Use sections to split longer processes into smaller parts, using Heading 1 to start and a line break and divider line to finish. Headings 2 to 4 can be used to create sub-sections, but don’t need a divider line. Every section must begin with an introduction.

🔎 Example:

Open the employee record (Heading 1)

Before you begin, you’ll need to open the employee record.

  1. Click Settings, then click Employee.

  2. Select the employee, then click Open.

---------------------------------------------------------------

✅ Do

❌ Don't

Save your export (Heading 1)

You can save your exported information following these steps.

  1. Click Admin, then click Reports.

Save your export (Heading 1)

  1. Click Admin, then click Reports.

Add a new account (Heading 1)

You can now add the account details.

  1. Click the Account tab, then click Add.

  2. Review the checklist, then click Next.

---------------------------------------

Check the items (Heading 1)

You can now check the items on the list.

  1. Select the item checkboxes you need.

  2. Click Next, then enter the details.

  3. Click Next...

Here’s how you add a new account.

  1. Click Settings, then click Employee.

  2. Select the employee, then click Open.

  3. Click the Account tab, then click Add.

  4. Check if you have the items on the list.

  5. Click Next.

  6. Enter the details then click Next.

Add the print options (Heading 1)

Before you start, ensure you have the margin measurements and paper weight.

Home printers (Heading 2)

If you have a home printer, follow these steps…

Industrial printers (Heading 2)

If you have an industrial printer…

------------------------------------

Add the print options (Heading 1)

Before you start, ensure you have the margin measurements and paper weight.

----------------------------------------

Home printers (Heading 2)

If you have a home printer, follow these steps…

----------------------------------------

Industrial printers (Heading 2)

If you have an industrial printer…

----------------------------------------

Quick reference checklist

Your article:

✅

Has an action-oriented, confident title.

✅

Has a clear and personal description.

✅

Has a confident introduction explaining the process.

✅

Has clear step-by-step instructions.

✅

Has sections to break up long information.

RACI

Task

Digital CS

DCL

DSL

DSE

Identify need for a how-to help article

C

A

I

R

Create first draft of article

I

C

I

R

Review content for quality, tone, and structure

I

A/R

I

C

Review technical accuracy

C

A

I

R/C

Review customer relevance

R

I

C

I

Approve final article for publication

I

A

I

C

Maintain article

C

A

I

R

Related Articles
Did this answer your question?