Google retired the HowTo rich result in 2023. That removed the reason most people added the markup and none of the reasons that still hold, which leaves a smaller and more honest case for using it.
The short version. Add it to genuine procedures in your documentation. Do not add it to anything you would have to restructure to make fit, and do not add it to a tutorial that is really an explanation with numbers on the paragraphs.
The shuffle test
Five seconds, and it settles the question for almost every page. Installing an SDK breaks if you shuffle it. Configuring a webhook breaks if you shuffle it. Ten ways to improve your sales process does not break if you shuffle it, which means it is a list and marking it up as a procedure is a small lie that a parser will believe.
Why the lie costs something. A HowTo declares that following the steps in order produces the stated outcome. If that is not true, you have told a machine something checkable and wrong, on a page where you were trying to build exactly the opposite impression.
What the markup is still doing
Three things, none of them visual.
- It states a completion state. A HowTo has an outcome, which is more than most content declares. That is useful to a system deciding whether your page answers “how do I connect X to Y” rather than merely discussing it.
- It gives each step an address. The
urlfield on a step points at an anchor, which lets a retrieval system cite step four rather than the whole page. This is the most underused field in the whole type. - It separates prerequisites from actions.
toolandsupplycarry what the reader needs before starting. Most tutorials bury that in the first paragraph where it is easy to miss and impossible to extract.
What it is not doing is making an unclear tutorial clear. Retrieval systems chunk text, and a well written numbered procedure already chunks cleanly without any markup at all. The markup confirms structure, it does not create it, which is the same point we made about FAQPage markup and for the same underlying reason.
A worked example
A real integration tutorial, marked up properly. The schema for this procedure is embedded in this page, so you can view source and see it in context rather than trusting the snippet.
{
"@context": "https://schema.org",
"@type": "HowTo",
"name": "Connect Northbeam to HubSpot",
"description": "Set up a two-way sync between Northbeam and HubSpot.",
"totalTime": "PT8M",
"tool": [
{ "@type": "HowToTool", "name": "A HubSpot admin account" },
{ "@type": "HowToTool", "name": "Northbeam on a paid plan" }
],
"step": [
{
"@type": "HowToStep",
"position": 1,
"name": "Open the integrations page",
"text": "In Northbeam, go to Settings, then Integrations, then Add.",
"url": "https://docs.example/hubspot#step-1"
},
{
"@type": "HowToStep",
"position": 2,
"name": "Choose HubSpot and authorise",
"text": "Select HubSpot from the list and sign in with a HubSpot
admin account when prompted.",
"url": "https://docs.example/hubspot#step-2"
},
{
"@type": "HowToStep",
"position": 3,
"name": "Map your fields",
"text": "Match Northbeam deal stages to HubSpot pipeline stages.
Unmapped fields are ignored rather than guessed.",
"url": "https://docs.example/hubspot#step-3"
}
]
}Two details in there are worth copying. totalTime uses the ISO 8601 duration format, so eight minutes is PT8M rather than anything more readable. And every step carries a url pointing at an anchor that genuinely exists on the page, which means adding id attributes to your step headings if they do not have them.
| Field | What it does | Commonly got wrong |
|---|---|---|
name | States the outcome | Set to the page title, which is usually a topic rather than an outcome |
step | The ordered procedure | Steps that are section headings rather than discrete actions |
step.url | Addresses an individual step | Omitted entirely, or pointing at an anchor that does not exist |
tool and supply | Prerequisites | Left empty while the prerequisites sit in prose above step one |
totalTime | Sets expectations | Guessed optimistically, or written as “8 minutes” rather than PT8M |
HowToSection | Groups steps in long procedures | Used to nest unrelated procedures that should be separate pages |
Documentation is usually the most cited thing a SaaS company owns, and almost nobody treats it as a marketing asset. If you want to know which of your doc pages engines actually reach, the free check covers crawl reachability across your whole docs tree.
Rules that still apply
The one that matters most for both machines and people is the fourth. Step text should be complete without the previous step. “Then click Save” is useless on its own and that is exactly how a retrieval system will encounter it. “In the Integrations panel, click Save” costs four extra words and survives being extracted.
This is the same discipline as answer-first writing applied at the level of a sentence. Write as though every paragraph might be read alone, because increasingly it will be.
Where this fits in documentation practice
The split between a tutorial, a how-to guide, an explanation and a reference is well established in technical writing, and the Diataxis framework is the clearest statement of it. HowTo markup belongs on the how-to guides and on nothing else. Tutorials in the Diataxis sense are for learning rather than for completing a task, and explanations are not procedures at all.
That distinction does more for your documentation than any markup will. Most SaaS docs mix all four modes on one page, which is why their pages are long, hard to extract from and rarely cited in full. The wider community around Write the Docs has a decade of material on this that predates anybody caring about AI and holds up unchanged.
Validate, then read it aloud
The schema.org reference for HowTo lists every available field, most of which you will not need. Google announced the retirement of the rich result on its search blog, which is worth reading if only to see how the reasoning was framed, since it applies to several other types that have not been retired yet.
Then do the thing that validators cannot. Read the steps aloud in order and do the procedure on a clean account. Roughly half the HowTo markup we check describes a sequence that no longer matches the product, usually because the interface changed and the markup was never on anybody list of things to review.
That is the real failure mode for this type. Not invalid syntax. Accurate markup describing a product that has moved on, published with more confidence than the page deserves, and never reviewed again.
Related reading
- FAQPage schema. The other type that lost its rich result, and the same reasoning.
- Product or SoftwareApplication. The type decision worth getting right before either of these.
- Schema markup for AEO. Which types pay out, ranked.
- The technical playbook. Where markup sits in the order of work.
Mark up the procedures. Leave the explanations alone.
HowTo is a small, honest type that describes one specific shape of content. Used on that shape it costs nothing and helps a little. Used on everything with numbers in it, which is what the rich result encouraged, it made a lot of documentation worse.
We send one piece a week on this sort of detail, with the testing behind it. Subscribe here.
Shaban runs answer engine optimisation for B2B SaaS companies at Uncited Brands. He works the unglamorous end of the problem, mostly crawler access, retrieval diagnostics and measurement baselines, and publishes the tests that do not go his way alongside the ones that do.