Designing Good Knowledge base Documents

This is a follow-on from my earlier Knowledge base Structure post, where I defined something called enterprise content, looked at describing your consumers, creating Catalogs, and creating some example documents that will ‘set the style’ for the content you are going to create.

This post is all about the enterprise content documents themselves – what I think works best, and some pitfalls to avoid.

Short Documents are Best

My own preference is for concise, single topic documents. In other words, don’t create documents that address a range of issues or subjects – it’s preferable to have a document that tells you how to fix a single 'something', or do something of value to the enterprise.

Sometimes content authors sit down to write content, and end up with a longer, more comprehensive document – maybe that covers a number of errors or problems, and shows you how to resolve each.

I tend not to favour this approach, and here’s why. Content consumers will be searching – either by entering a search term, or by browsing to the document from an intranet page. The consumer will want to make a quick decision about ‘Is this document right for me?’. The longer and broader your document is, the harder that decision making becomes, and the greater likelihood that your consumer will miss the solution you’ve taken time to create.

People can also be lazy. If their search yields a number of documents, the consumer may not ‘scroll down’ and instead only read the part of the document that displays ‘naturally’. This phenomenon has been known to search marketers for years, with content you have to scroll down to being referred to as ‘below the fold’ and generally regarded as much less visited.

Think About Your Format

Word, HTML, PDF – or something else? For each Catalog try to stick to a particular format. Remember Word is not the best format if your consumers are Internet visitors.

How will Documents be Linked?

Sometimes you’ll need one knowledgebase article to reference another, maybe to supply supplemental information to the consumer. If you are using HTML as your primary format, it seems natural to create a hyperlink between the two.

This seems fine – on the face of it. However, in creating that link you’ve just increased your support burden and created a dependence between the two documents. If you move the relative locations of the two documents, or rename the linked-to document, then your link no longer works.

A better approach might be as follows. Give each document an alpha-numeric reference number that appears in the title, and tell searchers to see ‘document …. for more information’. In other words, they have to re-search for the document using the reference you’ve given them. Although it is not quite so convenient for consumers, it does mean that you are free to re-organise your content from time to time without developing broken links within your content. Any changes you make will be handled by your indexing system.