A step-by-step help article works when a reader can finish the task without guessing. The writing is the hard part, but the layout and the screenshots matter just as much. Here is how to build one, and how to keep it right when your product changes.
Start with the goal: one article, one task
Each help article should cover one task. If you find yourself writing "and then, in another section, you can also...", split it into a second article.
The title should name the outcome, not the feature. "Invite a colleague to your workspace" tells a reader what they will get. "User management" makes them open the page to find out whether it is the answer they need.
Before you write any steps, check that you can state the goal in one sentence. If you cannot, the article will drift.
Write numbered steps that each contain one action
One step, one action. "Open the Team page and click Invite" is two actions, so split it into two steps. A reader who stops halfway through a long step loses their place. Short steps make it easy to find where they are.
Start each step with a verb: Select, Open, Type, Choose. Keep the sentences plain. If a step needs a reason, add it after the action, not before it.
Place a screenshot at each point where the screen changes, and crop to what matters
Add a screenshot whenever the screen changes in a way the reader needs to see. A new page, a pop-up, a form that appears after a click: each one earns an image. You do not need one for every step, and too many images make the article hard to scan.
Crop tightly. A full-screen capture of a 1920-pixel display shrinks the button you are pointing at to a speck. Crop to the part of the screen that the step is about, and leave enough context for the reader to recognise where they are.
Point to the exact button or field by its on-screen label
Refer to the label the reader will see on screen. Write "Select Save changes" rather than "click the save button at the bottom right". Labels match what is on the screen; descriptions of position go out of date when the layout moves.
Use the same name every time. If the button says Invite, do not call it Add user in step four. Readers will think they have gone wrong.
Blur personal data in screenshots, and how HandHoldly does this automatically
Screenshots often show names, email addresses and account details. Before you publish, look at each image and decide what should not be visible.
HandHoldly blurs personal data in the video, the screenshots and the article when it builds them, so you do not have to edit each image by hand. It is still worth a quick look at every screenshot before you publish, because you know your product's data better than any tool does.
Add short notes for what the person should see after each step
After a step that changes the screen, add a one-line note saying what the reader should now see. For example: "You should see a green banner that says Invitation sent."
These notes tell a reader they are on track. Without them, a reader who is unsure whether a click worked will either repeat the step or move on too early, and both lead to support requests.
Keep the article and the video in step by writing both from the same script
If you write the article and the video separately, they will drift apart within a month. Write one script, then build the article and the video from it. The steps, the labels and the notes stay the same in both.
For how to structure that script, see our post on writing walkthrough scripts. The same script can also produce a live guide inside your app, so one set of steps serves all three.
What to do when the product changes
Products change, and a help article that was right last month can be wrong today. HandHoldly runs a nightly re-check of each script. When a step no longer works, the re-check flags that step by name, fires your webhooks and emails the owners so someone can act on it.
Re-checks flag a broken step. They do not fix it on their own. The fix is yours to make.
With AI switched on, the tool can look for a button that has moved or been renamed and suggest the new label or position. AI is optional, and its suggestions are drafts for you to check. Once you have checked a suggested fix, you can save it into the script with one click. Read it carefully first: the tool can be wrong, and you are the one who decides what goes live.
For more on keeping scripts current, see our post on keeping help content right as the product changes.
A simple review checklist before publishing
Run through these questions before each article goes live:
- Does the title name the outcome of one task?
- Does each numbered step contain one action?
- Does each step start with a verb?
- Is there a screenshot wherever the screen changes, cropped to the relevant area?
- Does every button and field use the exact on-screen label?
- Have you checked each screenshot for personal data?
- Does each step that changes the screen have a note saying what the reader should see?
- Does the article match the current script and video?
- Have you tried the steps yourself, in the current version of the product?
If you can answer yes to all of these, the article is ready.
See the process in action
If you want to see a script turn into a help article with screenshots, See how it works.