You’re probably here because you’re sold on the idea of creating an extensive internal knowledge base all your employees can learn from and contribute to—but you don’t know where to start.
Don’t sweat it; we’re here to help!
The first step is writing a sound knowledge base article. After you finish the first one, others will follow, and soon enough, your database will be full of exciting and helpful information.
So, let’s start from the beginning and help you write a captivating first article.
Make a Plan
Writing without a plan will leave you with a haphazard article.
A disorganized article won’t be helpful or logical, so people are more likely to give up on it and try to look for answers somewhere else, rendering your efforts pointless. So, plan your article well instead of wasting time writing a text no one will read.
Before you start, think of what your audience needs. Is there a complex business process you rely on that might be unclear to newcomers? Maybe your workers have questions regarding a specific HR policy or course of action.
A known pain point or something your team finds difficult would be the best choice of topic for your knowledge base article.
After all, its purpose is to educate your team and share knowledge with them.
When you’ve selected the main topic, narrow your focus. For example, refund procedures might be the most complicated for employees.
However, don’t cover the entirety of refunds in one article. That way, you’ll give way too much information in one go, which will overwhelm the readers.
What is more, that kind of article would be difficult to structure coherently in the first place.
Instead, select a more specific topic like “refunding customers for defective items”.
By narrowing down the subject, you clarify what procedure you’ll be covering in the article, thus making it more helpful to those looking for this particular point.
Once you have the topic down, you can decide on the article type. It can be a “how-to” article explaining the process step by step or an FAQ article answering the most frequently asked questions regarding the topic.
When you’re describing a product’s features, consider making it a demo article.
People usually make video demos, but you can put the script in writing for those who can’t watch the video to find a specific piece of information.
If you want to write an extensive, informative article, go for a guide.
Once you decide on the topic and type of article, it’s time to map it out. What do you need to cover regarding the issue? List all the bullet points.
For the refunding case above, your bullet points could look something like this:
- Receiving the complaint
- Entering the complaint into the system
- Sending a refund request
- Notifying the customer
Then, think of any additional links or resources you can use to enrich the article.
In this case, you could attach a template the agent should send to the customer or instructions on entering the complaint into the system. If the point is a complex one, consider turning it into another article in its own right.
Craft a Clear Title
The best knowledge base articles have simple, to-the-point titles.
In other words, if you want your knowledge base to be informative, your article headlines have to explain what exactly you’ll cover.
Don’t beat around the bush or try to be secretive because your goal is to inform the reader, in this case, your employees.
Use a title that leaves no doubt about the article's topic and what answers you give in it. Whoever sees the headline should immediately understand what it contains. Otherwise, the chances of the reader clicking on the article are slim.
At the same time, the title has to be simple. You can’t type a 30-word headline and expect it to be helpful. People should be able to read the title without having to open the article because the number of words is too long for one line.
Therefore, don’t overcomplicate it, and avoid using long sentences as headlines.
Good Calculators offers a fun tool you can use for text readability analysis.
Write your title and click ‘calculate’ to see its overall readability score. Aim for simplicity and enhanced clarity. Otherwise, you might be alienating a part of the audience, which you do not want to do with company knowledge.
If you use humor throughout your knowledge base to make it more appealing, that’s great.
Nevertheless, you should still keep the title straightforward, no matter how much you want to add something to make it witty. This clarity will help your employees get the information they need fast.
When writing informative articles that describe how to solve a particular problem, the title should reflect that and be concise.
However, this doesn’t mean you have to give up on the witty tone in your writing overall. Keep your article funny and in line with your company culture but ensure the headline is straightforward.
When your employees log into the internal knowledge base, they will probably use specific keywords or type in a question to find an answer.
That’s why your title has to contain keywords or at least a verb they would use in their search. A verb makes something a complete thought, so your employees will have an easier time finding your writing if you use a verb in the headline.
The point is, think of what your readers will type into the search bar and then craft a simple and straightforward title based on that.
Write Your Article
If you want your article to be helpful, you must strike the right balance between simplicity and complexity.
You’re writing a knowledge base article on a particular topic because it is necessary. Perhaps the team doesn’t have enough information, or it’s simply a complex subject. Either way, you need to explain something complicated to the team.
The biggest challenge is that you have to figure out how to do that in a way they’ll understand. The readability calculator we’ve mentioned earlier can help you determine the simplicity of your text.
Of course, if you’re a company that prioritizes its company culture, you’ll have to make sure that the text reflects it too.
At the same time, you can’t pare down the article so much that it stops being informative. Oversimplified content will not be of any use to anyone other than new hires, making it useless for the majority of your team.
When it comes to the vocabulary you use, try to eliminate all overly complicated or technical terms. Instead, express yourself with simple, clear language that everyone can understand.
That way, all readers will have learned something from the article instead of clicking away from it with more questions than before.
If you can’t avoid using some jargon, make sure there’s a glossary somewhere in your knowledge base. This way, you’ll be sure anyone can understand the phrases you’re using.
Explaining every piece of jargon readers may struggle with is not just important for new hires, but it also makes sure that employees from different departments stay on the same page.
For example, customer service might not understand the jargon you use for the IT team, so if they have to look up a technical issue, an article filled with complicated terms might further confuse them.
Another great free tool you can use to check the readability of your writing is the Hemingway App, which also suggests what to cut out and what parts to rephrase to improve readability.
At the end of the day, your main goal when writing knowledge base articles should be to write something anyone from your team can understand and use.
Work on the Format
The format increases your chances of getting reads and, therefore, your article being useful.
Think about it: if you were looking for a solution to a work problem, would you rather read a wall of text or the same amount of content broken down into paragraphs?
When you format a text, try to break huge chunks of text into shorter sections for easier reading and, if necessary, skimming. After all, skimming is the way most users consume online content, with internet users reporting reading only a fifth of online texts.
In case of a longer article, it would be wise to insert anchor links at the very beginning. These links take the reader to the part of the article they’re interested in instead of letting them scroll or use the search option.
Headings and subheadings can also help the readers navigate through your articles.
Instead of having to read the whole thing to find a specific point, the readers can skim the article and locate the heading that covers the particular issue they’re researching.
Our documentation software, Archbee, allows you to use expandable headings. This function successfully hides everything written under a heading until you click on it.
That way, the page looks more organized and clean, and you get the information you’re looking for after clicking on the related heading.
Formatting also includes making the most important parts of text stand out. You can do this by:
- Using the bold, italics, underlining options (although the latter should be used sparingly, as the readers might interpret the underlined text as a link)
- Changing the size of the text
- Adding a highlight in a different color
When you have to list more options or a sequence, do what we just did and use bulleted lists.
All these formatting options can help bring your text to a new level of readability, which is your goal. After all, you want your writing to be easy to read, straightforward, and informative.
Even when dealing with complex topics, you can make something simple to read by dividing the text, highlighting the essential parts, and ensuring that there are no long blocks of text.
In fact, chunking texts improves content processing and affects how much of your article people remember.
Link Up Related Articles
Linking related articles or information takes your piece of writing to the next level.
When writing, you’ll often have to mention other problems, more significant topics, or general terms.
Suppose you’ve already written about these topics. In that case, the best option is to link the related articles so anyone who wants to know more or doesn’t know enough about the specific point can quickly get more information.
The simplest way to link other articles is to do it in-text. Highlight a part of text and select the linking option in the software you use.
This should allow you to paste the link to another article without showing the URL to readers. This way, your formatting and readability will remain intact, but you’ll offer further reading for interested readers.
With an easy click, your readers will be taken to the piece of writing that further explains the highlighted term. Here’s how you can do that in our knowledge base software!
When you want to mention a person or a document from your knowledge base, a simple @ will allow you to search the database for easy linking, meaning you don’t even have to copy and paste links.
If the text doesn’t offer an opportunity to link to an article, but you still think the readers should do further research, add a “related articles” section at the bottom of the text, thus giving good resources to those who want to know more.
Add Visual Elements
After you link relevant articles, it’s time to elevate your writing with various visual elements.
In the case of “how-to” articles, it would be wise to use screenshots for each step. For example, Salesforce does a great job explaining how to use the platform by including a numbered screenshot.
This screenshot is from the company’s external knowledge base, but you can take a similar approach for your internal one.
Why not use numbered screenshots when writing about something complicated, like using a new app or feature? It helps your team learn the basics and know more about all the available options.
In other instances, you can use video guides. Companies often use this type of media to explain company culture or the daily life of their employees at the company.
Google has made a video about the first week at their company as an intern, which can be used to onboard and attract new employees.
Of course, you can also use video for technical things, especially if you’re trying to make the article more interesting to readers. After all, videos can convey so much more information than text in a short timeframe, making them perfect for information sharing.
Whatever you use it for, a video will make an impression on your employees. Research shows that most people are visual learners, so if you want your team to retain information well, put it in a video!
Another good visual feature you can add to your articles is upvoting and downvoting. If an article gets a lot of upvotes, you’ll know you did a good job. However, if you notice an article keeps getting downvoted, it might be time to rewrite it.
Since downvoting is usually anonymous, you can expect to get honest feedback which will help you improve your internal knowledge base.
Review the Finished Article
Once you do all that, your article is almost ready to publish. The final step you should take is editing.
In this stage, you should reread your article and check its accuracy. Is everything you’ve said correct?
If there is incorrect information in your knowledge base, then employees won't know whether they can rely on it 100 percent, which will make it useless. Therefore, double-check the accuracy of your articles and the instructions within.
With quality documentation like Archbee, you can even invite other members of your team to confirm the validity of your statements and provide a fresh pair of eyes.
Then, determine whether everything is clear. It would be best to take a break before editing, so the information isn’t as fresh in your mind. Once you step away and come back, you will be better able to spot any inconsistencies or weaker points.
Of course, if you’re an expert at something, your text on the topic will be accurate, but ensure that it is also easy to follow even to newbies.
Finally, check if all your links work, if the readers can play the video, and if the images are the correct size.
Inserting a link that doesn’t lead anywhere won’t help the readers and will make you seem unprofessional, and the same goes for videos.
Images should follow the same guidelines and be approximately the same size. In fact, the visual elements should be pretty much uniform.
Once you’ve revised and edited everything else, proofread your article for spelling and grammar errors, as mistakes can make you seem untrustworthy.
In fact, research shows that people mistrust news articles that contain grammar errors. Why would work-related documents be any different?
This step is best left for last because every edit will require rewriting. There’s no point in checking the text for grammatical errors after every single amendment, as it would take a lot of time.
When checking your grammar, use a tool like Grammarly for better accuracy and faster results.
Conclusion
You don’t have to be a professional writer to write a quality knowledge base article.
However, you have to be an expert at what you’re writing or at the very least have a good idea of the topic. Otherwise, the article would be practically useless to the reader and would take up his or her time and mental energy for no reason.
If you’re familiar enough with the topic at hand, it will be easy to think of a good title and write down what you know. Don’t forget to format the article and make it look presentable.
You can always go the extra mile and insert links to related posts, policies, and articles, thus enriching your database. Finally, add some visual elements to make the whole thing more interesting.
Voilà, your first article is ready to share!
