Title Troubleshooting Pages With the Symptom
Users search for what happened to them, not for your internal explanation of why.
We renamed forty troubleshooting pages and search success went up by roughly a third. We changed no content at all.
The Old Titles Described Causes
“Clock skew in signature validation” is accurate and it is what the engineer who fixed it would call the page. Nobody searches for it, because the user does not know that is the cause. That is the entire reason they are searching.
The New Titles Describe Symptoms
“Webhook signature check fails intermittently” is what the person types. The cause goes in the first paragraph, where it belongs, and the page starts by confirming they are in the right place.
Include the Literal Error String
If your API returns invalid_signature, put that exact string in the page. People paste error messages into search boxes verbatim, and a page that never contains the string cannot be found by the most motivated searcher you have.
The Test
Read your troubleshooting titles and ask whether a user could have written them before understanding the problem. If not, the title is written for you rather than for them.
