TL;DR:
Each article covers one task, titled with what the customer is trying to do, not the feature name.
Write one action per numbered step, add a screenshot only where the screen is easy to misread, and say what the customer should see afterwards.
Test the article by following it exactly as written, ideally with someone who has not seen the product.
A customer who opens a help article is already a little stuck and often a little annoyed. They do not want a tour of your product. They want the next click. A good article gives them that click, then the next, and tells them when they are done.
When to write one
Write an article when the same question arrives for the third time, or when a support reply has become long enough that you are pasting it. The article then replaces the long reply with a link, and your answers stay consistent.
What to gather first
The exact words the customer uses for the problem ("I can't get in", not "authentication failure"). Use these in the title.
A working account to try the steps on, ideally one that looks like a new customer's.
A screenshot tool and a note of which screen sizes your customers use.
The name of the person who will keep the article current when the product changes.
Step by step
Cover one task: If the article says "and" in the title, it is probably two articles. Split them and link to each other.
Write the title as the customer's goal: "Reset your password" beats "Password management".
Open with one sentence on what this does and who it is for: Add any requirement up front, such as needing access to the email address on the account.
Write numbered steps, one action each: Start each step with a verb. Put the name of a button exactly as it appears on screen, in bold.
Add screenshots sparingly: Show the screen where customers most often go wrong. Crop to the relevant part and mark the target. Always keep the step text complete without the image.
Say what happens next: End with what the customer should now see, and what to do if they do not.
Test it, then publish: Follow the article exactly as written on a fresh account. Fix every place you had to guess.
Worked example: an article on resetting a password
The product here is invented, so button names are placeholders. Replace them with the exact labels in your own product. The draft below is the whole article.
The draft: Title: Reset your password What this does: Lets you choose a new password if you cannot sign in. You will need access to the email address on your account.
Go to the sign-in page and select Forgot password.
Type the email address you use for your account and select Send reset link.
Open your email. Look for a message from us. If you do not see it within a few minutes, check your spam or junk folder.
Select the link in the email. It opens a page asking for a new password.
Type your new password twice and select Save password.
You will see a message saying your password has been changed. Sign in with the new password.
If it did not work: If the link says it has expired, go back to step 1 and request a new one. Only the most recent link works. If you still cannot sign in, contact us and include the email address on the account. Never send your password.
Why it is written this way
Each step has one action, so a customer can look away to check their email and know exactly where to resume. The email step covers the most common failure, a message in spam, before the customer has to ask. The final line of the steps tells them what success looks like, so they do not wonder whether it worked.
Notice the last sentence about never sending a password. A help article is a good place for a short safety rule where a mistake is easy to make. Keep it to one line.
Where a screenshot earns its place
Step 2 is the one most customers misread, because the page has two similar boxes. A cropped screenshot of that form with the email field marked helps. Step 6 needs no image: the text already says what the customer will see. Describe the image in the surrounding text or alt text too, because some customers use screen readers and screenshots go stale after a redesign.
Mistakes to avoid
Writing from the builder's view. Use the customer's words and the labels on screen, not internal names.
Several actions per step. "Open settings, find security and turn off the toggle" is three steps.
Screenshots as the only instruction. If the image goes out of date or cannot load, the step must still work.
No ending. Without "you will see...", customers do not know whether they finished.
Skipping the test. Articles written from memory skip a step. Following your own text on a fresh account always finds one.
Doing it faster
Keep a template with the same layout: title, one-sentence summary, numbered steps, what happens next, what to do if it did not work. If you are drafting from your own screen, DuckyHelper can see what you are looking at and talk through what you did, which can help you recall steps, but you still need to run the final article by hand.
Frequently asked questions
How long should a help article be?
As long as the task needs and no longer. Most single-task articles fit in six to ten steps. If yours has far more, look for a place to split it.
How often should I check old articles?
Whenever the product screen they describe changes, and on a regular schedule such as every quarter. Put the date of the last check at the bottom.
Get started
