Tag Archives: web

Why do you have a ‘Knowledge Base’ on your website?

Question 1. Which of the following are indicated by having a ‘Knowledge Base’ on your company’s ‘support’ pages?

  • (a) A lack of the discipline needed to write proper documentation.

  • (b) Insufficient staff to provide proper support.

  • (c) Inadequate engineers to provide a reliable product.

  • (d) A poor user-interface experience in your product.

  • (e) All of the above.


The best thing about creating a website in blog format, I’ve always thought, is that you don’t need to maintain it to nearly the same degree as you would most other sites. Why? Because everything has a date, and that date is paramount; it is clearly marked. This makes it obvious to the reader that a post was written in a particular context, and, while the content may still be useful some years later, you can’t blame the author for not being able to predict the future if it’s no longer accurate or relevant now! As an author, therefore, you don’t need to be constantly re-reading, deleting, updating, clarifying, as you would with most other forms of documentation.

The appeal of the so-called ‘Knowledge Base’ — a searchable database of support articles on a company website — is that it also promises an alternative solution to this challenge of maintaining structured documentation, but instead of using old Father Time to winnow out inaccurate material, it uses a search engine to help you ignore it.

If you force your customers to type things into the Knowledge Base search box before you let them get anywhere near the page with your phone numbers or email addresses, there’s even a chance they may find out the answer to their question and not bother you! Bliss!

What’s the problem?

Search engines are wonderful things, of course, and this isn’t a bad idea in theory, but if your experience is anything like mine, these knowledge bases are chiefly a source of frustration for customers.

Why is this?

  1. Users don’t know what to search for. They may not know the phrases you use internally to categorise certain issues. A human support person would know that when you said you had an issue with your mouse, you might be referring to a problem labelled ‘trackpad’ or ‘cursor’ in the docs.

  2. The articles aren’t well-indexed. Do you, for example, make sure that the error message the user actually sees appears in plain text in the articles, so the search engine has a chance of finding it? Do your articles have extensive tagging with relevant keywords which may not be in the text? If the error is slightly different because they used a different filename, will it still be found?

  3. The search engines aren’t good enough. We’ve been spoiled by Google. Does your search engine understand synonyms? Does it rank pages well? Does it show a good summary so your users don’t have to read all 26 articles returned by their query?

  4. The content is outdated. If the user actually succeeds in finding a relevant article, is it clear that it only refers to version 4.2 of the product running on Android, and not version 5.0 running on iOS, because the latter didn’t exist at the time it was written? Will they know that the solution it proposes can’t possibly work for them? Because this advice is buried in a database, it may be harder for your support staff to know this is a problem.

How to fix it!

I have four pieces of advice for anyone who has, or is considering implementing, a Knowledge Base on their website:

  1. Make sure the full text of your knowledge base is searchable by Google. They will do a better job than you do.

  2. Allocate more, not less, in the way of resources, if you want your documentation in this form. Knowledge Bases are not like blogs. You can’t dump things in there and forget them. Articles need to be reviewed, re-written, re-indexed, re-keyworded and regularly purged if the contents are to remain useful. You need to do this in addition to writing the actually text itself. Customers will not thank you for anything which suggests you believe that their time is much less important than yours. If they have to search through dozens of articles to try and find an answer, it probably indicates you aren’t doing your job. There may be good reasons for using this format for your documentation. Cheapness isn’t one of them.

  3. If you insist on putting your users through this and they still contact you, you should provide better support once they do. For heaven’s sake, don’t just connect them to somebody in a remote location who only has access to the same information! Don’t offer a chat link to somebody who is ‘Very sorry to hear about your problem’ but knows less about it than they do. Connect them to the engineers who produced the flawed product, or the writers who produced the inadequate documentation.

  4. This is the key one: The bigger your Knowledge Base, the worse job you are doing. In most situations, an entry in your Knowledge Base indicates a failure in communication elsewhere. Insufficient documentation, unhelpful errors, unreliable products. Your users won’t generally be consulting a Knowledge Base if everything is going well for them. Treat it as an issue-ticketing system, and reward those whose work means that articles can be removed from it. And make sure you have the processes in place that this actually happens!

Stylish stylesheets

It’s somewhat ironic that, just as we get truly widespread SVG support in browsers – people are starting to create amazing graphics using CSS alone.

For those unfamiliar with the jargon, CSS stands for Cascading Stylesheets – they’re the things that tell your browser the background colour of a page, how widely spaced the lines in this paragraph are, and so forth. SVG is Scalable Vector Graphics, a system for telling the browser how to draw pictures, using components like lines, circles, etc. (as opposed to just embedding a JPEG-type image). SVG is particularly important as displays become bigger, smaller, and higher resolution, because the browser can draw things at the right resolution for even the newest retina MacBook Pro. It’s been around for a long time but has been held back by, of course, poor support in Internet Explorer. However, it’s now more widely supported than Flash, so if you can’t see this little doodle, you really need to find yourself another browser:

image/svg+xml Status Q

I scribbled this quickly in Inkscape, but here’s the beta version of a nice in-browser SVG editor.

But when it comes to artistic creativity, constraints are often a good thing, which is why some of the best photos are taken with prime lenses rather than zooms. And as CSS itself has become ever-more capable, it has allowed people like John Galatini to create this Tube map entirely from HTML and CSS.

CSS tube map

You can tell it’s not an image, because you can copy and paste the text.

Just as amazing is Burak Can’s CSS-only MacBook Air, where the screen background is the only image used.

On the other hand, people have been doing some cool but much simpler stuff with CSS for many years. I like Román Cortés’s Homer Simpson from 5 years ago; click the Animate buttons to see how it’s made.

Embarrassing admission

A conversation with friends this week turned to the subject of recipe websites: epicurious.com and suchlike. I realised that I’d never looked at any of these sites. Mmm.

In our household, we believe in specialisation of function, and, despite my offers to help out, Rose has always preferred doing the cooking to surrendering control of the kitchen! We’ve been married just over twenty years, hence my somewhat embarrassing realisation this week that the reason I’d never seen any recipe websites was actually quite simple…

The last time I looked at a recipe, there was no such thing as a website.

© Copyright Quentin Stafford-Fraser