Back to Blog Posts

Creating an Effective Knowledgebase 3: Writing Great Articles

By Sarah / April 1st, 2021

The first part of this series covered the basics of knowledgebases (here) and the second covered how to fill the knowledgebase you create in WHMCS with great content (check it out here). This part gets to the meat of things: writing your knowledgebase articles. Without great articles, there's no point to a knowledgebase, so let's get started crafting articles that will be useful, information-packed, and easy for you to maintain.

Remember as you write your articles: you're writing resources for the people who need your expertise, not the ones who know the answers.

Crafting Your Articles
Now that you've got your topics picked out and the contents outlined, it's time to "cheat." Gather up all the content you've already created in your past ticket history, internal records, and anywhere else you can think of. There will be more there than you think! This is where you start from, and the rest is just filling in the gaps. Then, all that's really left is to write the article itself.

It's important to pay attention to good spelling, grammar, and writing in general. Watch for the next post for more on this: there are some great tools than can help make sure you're writing cleanly.

Beyond writing basics, though, there are a few other things you might want to consider:

Consistency. You'll want to make sure what you write is consistent with what users see. Every setting name, interface name, file extension, and every other detail needs to match what the reader will see. After all, those details are how they know they're doing things right.
As an example, you might have an article troubleshooting license errors for an application you're selling through the WHMCS licensing addon. You would want to use the main text, like "License Key," "License Status," and "Reissue" as they appear on the page.

This can help your newer customers learn about the products they're using now, too. "Go to the Mailman interface in cPanel." won't be helpful to many people, since what they'll be seeing is an interface named Mailing Lists. Once they're in the article, though, they'll get to learn it, so an article that's more advanced could use "Mailman" with a reasonable expectation of the customer knowing the term.

Clarity. The last thing you want your knowledgebase to do is to leave readers asking more questions than you solved. Ambiguity can cause confusion, but you can correct this by being clear and specific ("click the Save button" rather than "save it") and using the same terminology every time ("shell" every time rather than "shell" once and "command line" once).

Completeness. You can also make things clearer by being methodical in your instructions: don't skip steps, even if you think they're obvious (like clicking Save or needing to enter a password).
To make your articles even better, give helpful information like where to find information that's being entered. For example, you might be writing an article that shows how to use the license key from earlier to activate an application. You'd want to give instructions to the location of that key in the WHMCS Client Area instead of just assuming the reader knows where to find it. Just that extra step's worth of information could save a lot of user frustration.

You don't want to go overboard, but it's better to have overexplained a little than to have left too much information out.

Company Identity. Your company has a brand and a voice, so think about how you can work that into your content. Are you businesslike and professional? Make sure your text is clear-cut and polished. Are you a quirky, fun brand? Keep your tone casual and friendly. Do you cater to nontechnical users? Tone down the high-tech terms with wording everyone can understand.
This doesn't have to be a big undertaking. Your customers should just feel like the articles were written by the same people they've dealt with and seen marketing from since their first experience with your company. It will help them feel comfortable and like they're "in the right place."

Presenting Your Information
The previous post talked about recommended outlines for topic and task posts, and that basic format still applies. For topics, introduce the topic, explain what it's used for, and then dive into the specifics, terms, and concepts. For tasks, define the task, why and when it's performed, and how and where you do it, plus any caveats or other helpful information. For every article, end with a call to action that directs the reader to the next logical task to perform.

The meat of every task article is the set of steps performed while completeing the task. The way you craft those steps is important. No matter how many times you've performed the task, take a moment to run through it and take notes before you write your article. Note every click, every decision, and everything that happens in response to your actions. After you have that set of notes in completely chronological order, it's all down to editing and formatting.

You'll want to separate the information with each numbered step corresponding to one action that the user performs. This means making sure that multiple actions are divided into multiple steps and that there aren't any numbered steps that don't include an action. It's helpful if the step starts with the action and then describes the action's results (if knowing the results will help the user orient themselves).

In general, do this:

1. Log in to the WHMCS Admin Area.
2. Go to Support > Knowledgebase.
3. Click on a category name.
4. Click on an article name.
5. Update the article as needed.
6. Click Save Changes. You will return to the list of articles for your chosen category.

And not this:

1. Log in to the WHMCS Admin Area and go to Support > Knowledgebase.
2. Click on a category name.
3. You will see a list of articles.
4. Click on an article name.
5. Make the change and save it.

While combining some of those steps can help simplify things, the more methodical your steps, the more likely that readers will have an easy, comfortable time reading and using them.

At the end of the steps, make sure to describe what happens after they complete the task. Is there a success message? Will they see a certain file or item listed in a certain place? Give them something they can self-verify against. It's helpful to keep steps streamlined and scannable, too, especially if it's a longer procedure. Extra information easily turns into noise if it's not what the reader needs. This means keeping any background or supporting information either before or after the list of steps accessible when the reader needs it but otherwise out of the way.

When your content isn't chronological steps, a lot more is dependent on your content itself. A few broad rules can be helpful, though: Keep your paragraphs short since more than 3-5 sentences in a single block can be daunting. If you're going in depth on a topic, make a quick outline and give your article an order that makes sense for a new user. Most importantly, keep a good handle on the amount of information you're working with. If things aren't fitting into an outline well and the article feels out of control, you probably need to split it up into a few different topics and put everything into smaller boxes.

Next Up
You've got your articles. They've got great content. What else could be left? A knowledgebase that's informative is the goal, but you can go even further to really make that information pop. The last segment in this series will help you add more value to your articles, organize them into categories that work for your customers and staff, and maintain that knowledgebase so that it's up-to-date and useful for years to come.

Liked this article? Share it