Discovered: Aug 10, 2026 07:25 (UTC) ME::tl-dr-ing this is true even without ‘AI’: Title the article as the exact question a customer would type, and put the direct answer in the first two sentences.** Don’t leave it implied by the heading or buried three paragraphs down. It needs to be in the body, early on. 100% agree with ‘The knowledge base is infrastructure whether anyone is treating it that way or not.’ ; Mark Sherwood Writing Knowledge Base Articles for Humans and AI that most

  • I agree that most humans don’t read the screenshots.
  • Apparently humans love animated GIFs and videos for explanations?!? I don’t (I love numbered steps. in text with screenshot) but I am old and grumpy :-). I prefer videos over animated GIFs because you can pause videos unlike animated GIFs.
  • I also agree that humans don’t read anything beyond the first 1-3 paragraphs unless you can convince them to read the rest which is extremely difficult unless they are paid to 100% know all the details and nuances and even then they are too busy to read past the first three paragraphs let alone the first paragraph.
  • I have also often well before “AI” thought that generic documentation doesn’t work. Instead have many statically documents rendered (so there’s minimal server cost with appropriate caching) each specialized to language, operating system, and application version and Thunderbird and Firefox version (and web browser version) if applicable in a standardized format . With “AI” as Mark Sherwood argues, that is is even more relevant. And of course there would some sort of UI/UX so folks could quickly home in on their specific document that they need.

QUOTE

“Click the button shown below” means nothing once the image is gone.

export one article, strip the images out, and then read a single chunk against the way a customer would actually ask the question, not the article title.

  • Most humans won’t be able to answer the question either since they won’t even look at your screenshot unless they are motivated somehow:

    If that chunk doesn’t answer the question on its own, the bot can’t either

Here’s the reframe to keep in mind. The AI agent didn’t add a new audience to write for. It exposed weaknesses that were already in the library.

The best way to handle all of this, and the template that ties all of this together starts with an answer-first opening block, followed by a one-line prerequisites statement, then a single procedure per page, with the product and plan named in the first paragraph.

Leave a comment on github