Before writing an article:
Most of the work in coming up with a knowledge base article is done before you actually write it. You have to make sure you understand what you are writing about, find pain points and put a structure around your whole article.
Understand user pain points.
Before writing a tutorial, try the entire step-by-step procedure yourself (and with a couple more people if you can). Note down where you got stuck, which step was confusing, what made you wait and any other mistakes you did along the way.
Write for the average user
You are not writing your knowledge base articles for just one kind of reader. What is easy for a power user may be too complicated for an average user. If you feel like you need to give more explanation for a newbie (or more information that a power user would like), split them into multiple articles and link them to the original one. This way, the article written for the average user doesn’t have too much information.
Cater to different kinds of learners
Different people learn differently. Some like to learn using images and videos while some like to try out things step by step. That doesn’t mean you can bog down the article with screenshots. Figure out the minimum number of screenshots that will explain the process, and whether that particular article deserves a video.
While writing the article:
Now that you’ve figured out what you should be writing about and what points you should get across, it’s time to actually write the articles. Here, you should make sure you stick to some basics and you actually follow through on your plans.
1) Talk like your users talk.
Do not use over-the-top words or technical jargon in your articles. Find out what customers call the feature you are writing about (using search terms in GA or by reading tickets) and use those words in the article and its title.
2) Be straightforward.
Your articles need to be easy to scan through and understandable in just one read. The title and subtitles should cover what you are trying to say. If you are interested in making things look good, personalize the design, not the content
3) Feature trumps benefits.
When you write for your support portal, remember that you are not trying to sell. A solution article is written to help, not to convince. So your articles should talk about the nitty-gritty of the features more and benefits less.
4) Treat every article as a mini-onboarding process.
Start by explaining the feature in simple words. Then, use an example to show what the customer can do once she follows your instructions. This way, even if the setup process is elaborate, users will stick to it till the end.
5) Bullets and tables are your best friends.
Needless to say, formatting solution articles is extremely important. Clearly, differentiate your titles and subtitles. Split different sections using a horizontal line. Bold the action items in each step so it’s easy for readers to skim.
6) Always state the prerequisites.
Don’t make it hard for users to find out what a feature cannot do. If your reader needs something to get started, begin your article with that information.
7) Nothing is too obvious.
Don’t leave out even the tiniest of details assuming that it’s obvious. Use a table or create annotated screenshots when you want to explain many little things without making the article too long.
After writing the article:
You’ve finally finished writing your article. All your work is done, you can move on to the next task and forget about this one, right? Nope.
You are not done writing a support article once it’s published. You have to make sure that it is useful, that it’s up-to-date and that it is organized well.