The key to writing a good knowledgebase article is understanding your audience. Think about the problems they frequently experience and the questions you receive in emails and phone calls. Below are some practical tips for researching and writing good knowledgebase articles. Please review the BC Knowledge Article Style Guide as well.
Who is the intended audience of the article?
Are you writing an article for students, faculty, or staff? What is their level of experience? Try to put yourself in their shoes and write the article from their perspective.
Limit your article to one idea
Keep your articles short and focused. A typical article should answer one question or explain how to accomplish one task. If you need to write a more comprehensive guide, consider breaking it up into multiple articles or clearly labeling it as a guide. Shorter articles are also much easier to categorize and find in the site search.
Talk to your intended readers
If you need more clarity on what to include in your articles, schedule a short interview with someone from your intended audience. You’ll gain valuable insights on the types of articles you should write and the level of detail to include.
Use headers or lists to break up your article
Headers give your article a clear structure and are used to create an automatic table of contents for your article. Use ordered lists when explaining steps, sequences, and processes.
Include visuals for clarity
Use images, charts, and videos to simplify your articles. BC Knowledge supports all common image and video formats. Consider adding screen recordings to demonstrate software tools and online processes. Learn more about taking screenshots and recording your screen using Camtasia Studio.
You can copy and paste screenshots directly into your article or upload images and videos using the media block.
Create links between your articles
Linking between pages is the fundamental principle of the web. If you find yourself rewriting the same information in multiple articles, consider moving that information to a dedicated article and linking to it from your other articles. Not only does this save you time, but it makes it easier to update this information in the future. It also allows readers to find this information in the search. (It’s also probably important information if you’re repeating it in multiple places.)
A good example you’ll see throughout BC Know is the link to the IT Helpdesk page. Instead of repeating the contact information and description for the Helpdesk, we link to the page from multiple articles. This way, if anything changes about the Helpdesk in the future it only needs to be updated in one place.
