Question-based headings: writing the heading people actually search
"Credential Rotation Policy" was written by the team that owns the page. Nobody types it. The person looking for it types "how often should I rotate an API key", and the fix is to move one heading closer to them without turning the whole page into a questionnaire.
The short answer
Question headings match the way people actually phrase a search, which is increasingly a full question rather than three keywords. Rewriting "Pricing structure" as "How much does it cost?" costs nothing and reads better. The failure is turning a whole page into an interrogation, where every heading is a question and the outline stops describing an argument.
Headings written from the inside out
Internal headings fail in three recognisable ways, and once you can name them you see them everywhere in your own documentation.
- The org chart."Platform Enablement", "Partner Operations", "Customer Success Resources". These name the team that produced the page. A reader looking for the thing the page does has no route from their words to yours.
- The nominalisation."Configuration of webhook endpoints" instead of "How do I set up a webhook?". The verb has been turned into a noun, which is how specifications are written and not how questions are asked. This is the most common of the three and the easiest to reverse.
- The internal product name. A heading naming a feature only your customers know by that name, or worse, only your engineers do. It is searchable by people who already use you and invisible to everyone else, which inverts what the page was probably for.
The common cause is that headings get written last, by the person who has just spent a week inside the subject, at the point where the internal vocabulary is the only vocabulary left in the room.
The forms a real query takes
A short list covers nearly all of it. "How do I" for a procedure, "what is" for a definition, "why does" for a diagnosis, "can I" for a capability, "when should" for a decision, "does X support Y" for a compatibility check. Match the form to what the section genuinely provides and the heading writes itself.
Two things this is not. It is not about punctuation: "setting up a webhook" is a query and carries no question mark, and a heading in that shape counts here. This check reads for interrogative form rather than for a trailing symbol, which means adding question marks to your existing headings changes nothing at all.
And it is not about length. "Why is my API key returning 401?" is longer than "Authentication errors" and better, because it contains the thing the reader has in front of them: the number on their screen. Specificity is what makes a question heading match, not brevity.
Reading an outline the way this check reads it
Strip a page down to its headings and read them as a list, with no body text between them. A reader arriving from a search skims exactly that, and the defect is much more obvious in the list than it is in the page.
This one needs the full crawl
This reads every heading on a page and weighs the phrasing against the question forms people search with, which needs the whole outline rather than any single element.
The instant search on this site audits a single page, so rather than show you a verdict it cannot support, this guide sends you to the place the check actually runs.
One outline, rewritten
The whole edit, on a page that exists on most developer-facing sites. Note that two headings survive as labels, which is deliberate.
<!-- Before. Six headings in the site's own vocabulary.
None of them is a phrase anyone types. -->
# Platform Enablement Overview
## Prerequisites
## Key Provisioning
## Credential Rotation Policy
## Troubleshooting Matrix
## Reference
<!-- After. Same six sections, same order, same content.
Four now match a query; two stay as labels because
that is what they are. -->
# Setting up API access
## What you need before you start
## How do I create an API key?
## How often should I rotate a key?
## Why is my key returning 401?
## Reference
<!-- The part that gets forgotten: pin the old anchor so
existing links keep landing. This is rehype-slug
syntax; in plain HTML it is
<h2 id="key-provisioning">How do I create an API key?</h2> -->
## How do I create an API key? {#key-provisioning}"Reference" stays because nobody searches for a reference table by asking a question, and "Prerequisites" becomes plain language rather than a question because the section is a list of requirements, not an answer. Forcing either into interrogative form would be following the rule past the point where it helps anyone.
Rewriting a heading renames its anchor
This is the practical cost of the edit and the one nobody plans for. Most documentation stacks generate heading ids from heading text, so changing "Key Provisioning" to "How do I create an API key?" silently moves #key-provisioning to something new. Every link into that anchor now lands at the top of the page instead.
The links that break are the ones you cannot see: support macros, an onboarding email from two years ago, a Stack Overflow answer, another team's runbook, the in-product help link. None of them appears in your own site's link graph, so nothing warns you.
Pin the id explicitly, as in the last block above, and the rewrite becomes free. If your generator gives you no way to override it, add a redirect for the fragment or leave a zero-height anchor with the old id in place. Then re-crawl, because your own internal anchors and any on-page contents list did break and the broken-link check will show you where.
The page that turns into an interrogation
Nine consecutive question headings do not read as helpful. They read as a form.
The overcorrection is mechanical: someone runs the rule down a page and converts every heading, including the ones that were correctly labels. What comes back is a document with no spine, because a question heading tells the reader what is being asked and a label heading tells them where they are. A page made entirely of the first is one you cannot navigate.
Structural headings should stay structural: "Requirements", "Pricing", "Limits", "Changelog", "API reference". Question headings belong on the sections that answer something. The check reports the balance rather than a count, so a page of all questions flags as readily as a page of none, and the reason is the same in both directions: the phrasing stopped following the content.
What the check cannot know about your readers
Worth stating plainly, because this check produces more arguable findings than most. It reads your headings and weighs their phrasing against the forms people search in. It has no access to your search volume, your audience or your analytics, which means it cannot distinguish a heading that is wrong from one that is right for a specialist reader.
On an API reference read exclusively by engineers who arrive from your own sidebar, "Rate limits" is the correct heading and the check will still flag it. Treat that as an invitation to look, not an instruction to edit. The finding is strong on marketing pages, help centres and anything acquiring readers from search, and weak on documentation people arrive at already inside.
It also cannot tell whether the passage under a rewritten heading answers the question it now asks. A heading promising an answer and a section that never delivers one is a worse page than the label version was, and that gap is the subject of the direct answer check rather than this one.
Why this one is only a Refinement
It is the lowest-rated check in this group and the rating is right, even though rewording headings is often the first thing anyone sells you. Nothing is broken on a page with internal headings. It is crawled, indexed, ranked and read, the outline is valid, the content is intact. What you forgo is a closer match on queries you may already appear for.
The test that separates Refinement from Important on the scale is whether anything downstream depends on the check. Here, nothing does. Markup works with a label heading. A snippet can be lifted from under one. An answer passage reads correctly beneath one. Compare that with an answer that opens on a pronoun, which no amount of good markup rescues.
Lowest severity, highest ratio of gain to effort. Those are not in conflict.
The cost is one line of copy per section and no engineering, apart from the anchors. That makes it a good thing to do while you are already editing a page and a poor thing to run a project for.
Does this affect AI search? Less than it helps a searcher
This is the weakest AI case of any check in the group, and pretending otherwise would be easy and wrong. Retrieval works on meaning rather than on matching strings, so "Configuration" and "how do I configure this" land close together in the representation a model uses. The lexical mismatch that costs you a classic search match costs you much less here.
There is one real second-order benefit. When a page is split for retrieval, the heading usually travels with the passage beneath it, so a heading phrased as the question makes that fragment self-describing: the chunk states what it is answering instead of relying on a section title three levels up. That is the same argument as segmentation, operating on six words instead of on a section.
The honest ordering, then: do this for the searcher and take the retrieval benefit as a by-product. If AI visibility is the actual goal, the checks in that group about crawler access and text that survives without JavaScript are worth more than every heading on your site put together.
Reading the new outline back
Extract the headings again, on their own, and read them as though they were a list of questions someone sent you. Each one should be answerable, distinct from its neighbours, and phrased in words a reader would use unprompted. Two headings that now ask nearly the same question are the usual artefact of the rewrite, and they mean the sections should merge.
Then look at the query data for the page a few weeks later. You are not looking for a traffic jump, which will be indistinguishable from noise on most pages. You are looking for the set of queries to shift towards the phrasing you adopted, which is the only confirmation available that the rewrite matched how people actually ask. And re-check the anchors, since a fragment that stopped resolving is the one way this edit can leave a page worse than it found it.
Questions this check raises
- Should all my headings be questions?
- No. A page where every heading is a question reads as an interrogation and its outline stops describing the shape of the argument. Use questions where the section genuinely answers one, which is usually a minority of the headings on a page.
- Do question headings help with voice search?
- They help with any query phrased as a question, spoken or typed, because the heading matches the phrasing. Voice is the case most often cited and it is not the largest one: the shift toward full-sentence queries happened in typed search too.
- Does changing a heading break anything?
- It renames the anchor if your anchors are generated from heading text, which breaks every existing link to that section, including ones on other sites. Worth checking before a bulk rewrite, and worth pinning anchors explicitly if you rewrite headings often.