Insights
What years of running help centers taught us
What we have learned running knowledge bases at scale, written up properly: the reasoning, the evidence, and what we would actually do about it.
If you only have five minutes, the lessons are shorter and cover one idea each.
13 field notes
My AI bot gives wrong answersReading was never the problemSomeone ran 2,400 tests to find out what AI agents get wrong. Reading wasn't the problem. Finding the page was.Read itMy AI bot gives wrong answersStart hereWhy your support bot keeps giving customers wrong answersA customer asks your bot a question, it answers confidently, and it's wrong. The bot isn't guessing. It's reading your articles back to you.Read itMy AI bot gives wrong answersSilence in your documentation is not neutralThe most expensive sentence in your help center is the one you never wrote. A machine reading your docs can't tell a deliberate omission from a gap.Read itAI tells people the wrong thing about my productWhat actually makes an AI quote youYou can't control which pages get retrieved. You can control whether a passage is safe to quote once it arrives, and that's most of the battle.Read itMy docs are outdatedWhy most of your articles shouldn't be fixedImproving an old article is the most expensive thing you can do with it, and usually the wrong call. Here's how to decide faster.Read itAI tells people the wrong thing about my productYour documentation might be invisible, and nobody has checkedA docs site can be unreadable by every AI system for a year and produce no signal at all. Nothing errors. Your traffic looks normal.Read itEveryone on my team writes differentlyWhy AI can't tell that 'workspace' and 'team space' are the same thingRetrieval handles ordinary synonyms well. It cannot handle yours, because nothing outside your company knows that two of your words mean the same thing.Read itMy screenshots are always out of dateA fact that lives only in a screenshot doesn't existThe screenshot shows the setting is under Advanced. The text never says so. To anything that can't see the image, that fact does not exist.Read itMy docs are outdatedYour duplicates aren't three chances to rankThree articles on one topic isn't three chances to be found. It's one chance split three ways, and a bot that answers differently depending on which one it grabs.Read itI'm drowning in support ticketsHalf of what you're asked to document isn't a docs problemA documentation backlog isn't a writing queue. It's a symptom list, and about half of it is telling you something is wrong with the product.Read itMy AI bot gives wrong answersSample the conversations that looked successfulEveryone reads the conversations where their bot failed. Almost nobody reads the ones that looked fine, which is where the expensive mistakes are.Read itMy docs are outdatedYour changelog is the only dated thing you publishHelp articles have no clock in them. Your changelog is the one place you publish that says when something was true.Read itI need to write help articlesMost help articles fail on structure, not writingThe sentences are fine. The problem is that the answer is in paragraph six, and half the article only makes sense if you started at the top.Read it