The No Bullsh*t Guide to Knowledge Bases: Part 3

You published your help article...and everyone ignores it. So why? And how do you fix it?

River Sloane

Apr 30, 2026 • 14 min read

Nobody reads your articles (and it's your fault)

You wrote the article. You published it. You linked a customer to it. They replied twenty minutes later asking the exact question the article answers.

And you thought: why do I bother? 🥺

Here's the uncomfortable truth. They probably did click the link. They probably did look at the article. And then they bounced off it like a bird hitting a window, because something about it made their brain go "nope, not reading all that."

"Which raises the obvious question: why didn't you just write it like that in the first place?"

Maybe it was the wall of text. Maybe it was the corporate voice that sounds like it was written by a legal team having a bad day. Maybe it was the seventeen steps when there should have been three. Maybe it was just... boring. Aggressively, defensively boring.

The kind of boring that feels intentional.

Whatever it was, they gave up. They closed the tab. They emailed you instead. And you answered their question in two sentences, in plain English, like a normal person.

Become an expert in all things Knowledge Base with our monthly newsletter. No spam, just expert content, delivered.

Which raises the obvious question: why didn't you just write it like that in the first place?

The customer only cares about the answer

I'm sorry, but this needs to be said.

The person reading your documentation does not care about you. They don't care about your company. They don't care about your product philosophy, your mission statement, your commitment to customer success, or the thoughtful design decisions behind your interface.

It's by no means personal. They have a problem. They want it fixed. That's it.

They're not browsing your knowledge base for fun. They're not settling in with a cup of tea to enjoy your carefully crafted prose. They're annoyed, probably a bit stressed, and they want to find the answer as fast as humanly possible so they can get on with their day and never think about this again.

Your documentation is not content. It's not an opportunity to build brand affinity. It's not a chance to showcase your company's personality. It's a speed bump between them and their goal, and the best thing it can do is get out of the way as quickly as possible.

People are lazy. Not in a bad way.

In a "I have a hundred things to do and this is not how I wanted to spend my afternoon" way. They will take the path of least resistance. If your article is long, they'll skim it. If it's confusing, they'll give up. If it's easier to email support than to read your docs, they'll email support.

Every word you write is a word they have to read.

Every sentence is a hurdle.

Every paragraph that doesn't directly answer their question is a reason to close the tab.

This isn't about your writing being bad. It's about understanding that nobody owes you their attention. You have to earn it by being useful, fast. Anything else is just getting in the way.

Gen Z is really not going to read your article

And it's about to get worse.

I say this as a millennial who grew up reading magazines and waiting for websites to load over dial-up: the attention economy has moved on. Gen Z grew up on YouTube tutorials and TikTok.

"This isn't a moral failing. It's just how brains work when you've been raised on video content"

Their default isn't "I'll read about how to do this." Their default is "I'll watch someone do it."

This isn't a moral failing. It's just how brains work when you've been raised on video content. Reading a 500-word article about how to change a setting feels like work. Watching a 45-second screen recording of someone doing it feels like nothing.

So if your knowledge base is text-only, you're already losing a chunk of your audience. Not because your writing is bad. Because the format is wrong for how they learn.

This doesn't mean you need to become a YouTuber and start making those really annoying thumbnails. It means thinking about other formats:

Short videos. Loom, Screen Studio, whatever. Record yourself doing the thing. No editing, no polish, just "here's how you do it." Embed it at the top of the article. People who want to watch can watch. People who prefer reading can scroll past.
Interactive walkthroughs. Tools like Arcade or Glitter.ai let you create click-through demos. Instead of reading about where to click, they click through a simulated version. It's learning by doing, without the risk of breaking anything.
GIFs. Sometimes a three-second looping GIF is worth more than three paragraphs of explanation. "Click here, drag here, done." They can see exactly what to do.
Collapsible sections. If you have to include detail, hide it by default. Give them the short version upfront, let them expand if they need more. Don't force everyone to wade through the advanced stuff to get to the basics.

The point isn't to replace all your articles with videos. It's to recognise that a wall of text isn't the only way to help someone, and for a growing chunk of your audience, it's actively the worst way.

Meet people where they are.

Some will read. Some will watch. Some will click through an interactive demo. Your job is to help them, not to force them into your preferred format.

The curse of "professional" writing

Somewhere along the way, someone decided that documentation needs to sound Professional. Capital P. Formal. Serious. Like it was written by an institution rather than a human being.

So instead of writing "Click the blue button," people write "Users should navigate to and select the appropriately coloured action button located in the interface."

Instead of "This won't work if you're on the free plan," they write "Please note that this functionality may be subject to limitations depending on your current subscription tier."

Instead of "You need to do this first," they write "Prior to proceeding with the subsequent steps, it is necessary to ensure that the prerequisite actions have been completed."

Nobody talks like this. Nobody thinks like this. And absolutely nobody wants to read it.

But people keep writing like this because it feels safe. It feels like what documentation is supposed to sound like. It's what everyone else's docs sound like, so it must be right.

It's not right. It's just tradition. Bad tradition. The kind of tradition where everyone's doing it because everyone's always done it, and nobody's stopped to ask "wait, is this actually working?"

How your docs actually sound

Let's play a game. Go read one of your help articles out loud. Actually out loud, not in your head.

Does it sound like something you'd say to a customer if they were standing in front of you? Or does it sound like you're reading from a terms of service document while trying not to make eye contact?

If it's the second one, you've got a problem. Here are some warning signs:

You use "users" instead of "you." "Users can access their settings" vs "You can access your settings." One sounds like a policy document. One sounds like you're actually talking to a person. Guess which one people prefer.
You hedge everything. "This may help resolve the issue." "You might find this useful." "In some cases, this could potentially..." Just say the thing. If you're not sure, say you're not sure. But stop wrapping every sentence in cotton wool.
You write in passive voice. "The button should be clicked" vs "Click the button." Passive voice isn't always wrong, but if your entire article reads like nobody's doing anything and things are just mysteriously happening, it's exhausting.
You start with backstory nobody asked for. "At [Company], we believe that empowering our users with the tools they need is fundamental to..." No. Stop. They want to know how to reset their password, not your mission statement.
Your sentences are forty words long. If someone has to read a sentence twice to understand it, you've lost them. Short sentences. Simple words. Say the thing, then stop.
You explain things in the wrong order. You tell them why before you tell them how. You give context before you give instructions. But they don't want context. They want to fix their problem. Context is a luxury for people who aren't frustrated.

Write like you're answering a ticket

Here's the cheat code: you already know how to write good documentation. You do it every day. It's called answering support tickets.

When someone emails you with a problem, you don't write "Users experiencing this particular issue may find that the following steps could potentially resolve their concerns." You write "Hey! Try this: [steps]. Let me know if that doesn't work."

That's it. That's the voice. Friendly, direct, human. You already have it. You just forget to use it when you open a blank document and your brain switches into "official content" mode.

So trick yourself. Don't think "I'm writing documentation." Think "I'm answering a ticket, except I'm going to save it somewhere useful." Same energy. Same tone. Same "let's just fix this" attitude.

If your article doesn't sound like something you'd send to a customer who emailed you at 4pm on a Friday, rewrite it until it does.

The actual structure that works

Forget everything you learned about essay writing. Introduction, body, conclusion? Bin it. Nobody's grading you on structure. They're trying to fix a problem while their boss breathes down their neck.

Here's what actually works:

Start with what they need to do. Not why. Not background. Not "welcome to this guide." The first sentence should be useful. "To reset your password, click here and follow the prompts." Done. They might not need anything else.
Then give the steps. Numbered. Short. One action per step. Not "Click Settings, then navigate to Account, and from there select Password, then click Reset." That's four steps pretending to be one. Break it up.
Then handle the "what ifs." What if it doesn't work? What if they're on mobile? What if they don't have access? Put these at the end, clearly labelled, so people who need them can find them and people who don't can ignore them.
Skip everything else. You don't need an intro paragraph. You don't need a summary. You don't need a "we hope this was helpful!" outro. You need instructions that work. That's it.

The best documentation is the stuff people barely notice because it just answers their question and gets out of the way.

Your article is 8,000 words long. Who is this for?

Let's talk about the monster articles. The ones that started as a simple how-to and grew, over years, into a sprawling epic that covers every possible scenario, edge case, and tangentially related topic.

Eight thousand words. Twelve sections. A table of contents that scrolls. FAQ at the bottom with fifteen questions, some of which contradict things you said earlier because you forgot what you wrote in paragraph thirty-seven.

"If someone has to use Ctrl+F on a single article to find what they need, something has gone horribly wrong."

Who is this for?

Not the customer, who wanted to know how to change their email address and is now staring at a novel. Not the support team, who have to link to it and pray the customer finds the relevant bit somewhere in the middle.

Not you, because every time the product changes you have to update this behemoth and hope you caught all the places it's now wrong.

If someone has to use Ctrl+F on a single article to find what they need, something has gone horribly wrong.

That's not documentation. That's pointless.

Here's the rule: one article, one topic. If your article covers multiple distinct things, it should be multiple articles. If your article has twelve sections, at least eight of those should probably be their own page. If your article requires a table of contents, you've written a wiki, not a help doc.

"But they might need all of this information!" No.

They might need some of this information. Probably one specific bit. And right now that bit is buried in a 20-minute read alongside a bunch of stuff they don't care about.

Split it up. Link between articles. Let people find the specific thing they need without wading through everything else.

Short, focused articles that answer one question are infinitely more useful than comprehensive articles that technically answer everything but practically answer nothing because nobody can find anything.

Your article should take two minutes to read, max. If it takes longer than that, it's either covering too much or you're using too many words. Either way, fix it.

Stop making them read so much

Here's a hard truth: people don't read. They scan. They're looking for the bit that applies to them so they can fix their problem and move on with their lives.

If your article is a wall of text, they're not going to carefully read every word looking for the answer. They're going to skim it, miss the relevant bit because it's buried in paragraph four, and email you.

So make it scannable:

Use headings. Lots of them. Let people jump to the section they need.
Bold the important bits. If there's one key thing they need to do, make it stand out.
Keep paragraphs short. Three sentences max. Give their eyes a break.
Use screenshots. Show the thing, don't just describe it. But also don't use twelve screenshots when three would do.
Cut the waffle. Every sentence that doesn't help them solve their problem is a sentence that's getting in the way. Be ruthless.

You're not writing a novel. You're writing instructions. The best compliment someone can give your documentation is "that was quick."

The "I'll sound unprofessional" fear

This is the thing that stops people writing in plain English. The fear that someone important will read it and think it's not serious enough. Not polished enough. Not... professional.

Let's address this directly: nobody has ever complained that documentation was too easy to understand.

Nobody has ever said "I found the answer immediately, but I wish it had been more formal." Nobody has ever thought "these instructions were clear and helpful, but the tone felt too casual."

What people do complain about is not finding answers. Not understanding the instructions. Giving up and contacting support. That's what unprofessional documentation looks like. Not the tone. The outcome.

Your docs can be friendly and accurate. They can be casual and useful. Those things aren't in conflict. The most professional thing you can do is actually help people.

If your company has a style guide that demands formal language, push back.

Show them the support tickets from people who couldn't understand the docs. Show them the data on how many people visit the knowledge base and still email support. The formal voice isn't protecting anyone. It's just making more work for everyone.

A word on screenshots

Screenshots are essential. Screenshots are also a maintenance nightmare. Both things are true.

Here's how to not make it worse for yourself:

Don't screenshot everything. You don't need a picture of every single step. Use screenshots for the confusing bits, the "where the hell is that button" moments, the things that are hard to describe in words. Skip them for the obvious stuff.
Annotate properly. A screenshot with no context is just a picture. Add an arrow. Circle the button. Highlight the thing they're supposed to click. Don't make them play Where's Wally.
Crop them. Nobody needs to see your entire screen. Show the relevant bit. Tighter crops also make it easier to see what's important.
Accept they'll go stale. Your UI will change. The screenshots will become outdated. This is inevitable. The goal isn't to prevent this (you can't), it's to make updating them as painless as possible. Use tools that let you quickly regenerate screenshots by clicking through the flow again. Manual screenshotting for every update is a trap.
Use them to replace explanation, not add to it. If you can show something in a picture, you often don't need to describe it as well. "Click the Settings icon (see below)" is fine. You don't also need to write "The Settings icon is a grey gear-shaped button located in the upper right corner of the navigation bar." The picture already did that, and use alt text to describe the image instead.

The editing pass nobody does

You've written the article. You're pretty happy with it. You publish it and move on.

Don't. Not yet. Read it once more and ask yourself:

Can I cut the first paragraph? Often yes. You probably started with context or introduction that nobody needs. The article usually gets better if you just delete the beginning.
Can I cut any sentences? If a sentence doesn't add new information or help them complete the task, it's just in the way.
Can I make any sentences shorter? Long sentences are harder to follow. Break them up. Use full stops. Give people's brains a rest.
Would I actually say this out loud? Read it as if you're explaining it to someone. If it sounds weird spoken, it probably reads weird too.
What question will they ask after reading this? Whatever it is, answer it. Either in this article or by linking to another one. Don't leave them hanging.

This takes five minutes. It makes the article significantly better. It's the difference between documentation that technically exists and documentation that actually helps.

You're not writing a masterpiece

The goal is not beautiful prose. The goal is not impressing anyone. The goal is not creating content you're proud to put your name on.

The goal is: someone has a question, they find your article, they get the answer, they leave.

That's it. That's success. They shouldn't remember your documentation. They should remember that they solved their problem.

Write it clearly. Write it simply. Write it like you're talking to a person who's slightly annoyed and just wants to fix their thing.

And stop calling them "users." They're people. Write like it.