How To Write A Knowledge Base Article
There are a lot of competing things to balance when writing or editing an article. You want to be complete and concise; factual and engaging all at the same time. It’s certainly not the easiest thing in the world to do. Here are some guidelines to help make that balancing act a little easier. Also, this is a wiki and we can always revise something if we get it wrong.
Picking a good title
When picking a title for an article we want to try to match what people are searching and browsing for — to match the question they might ask you in person. Here are some examples of the kinds of titles you should pick:
- For a tutorial or how-to article: How do I achieve this result? (e.g., How do I set the home page?)
- For a reference article: What is/are the topic(s)? (e.g., What are App Tabs?)
- For a case: This is the problem I’m having (e.g., Firefox takes a long time to start up)
Techniques for making your writing engaging
UNAVSA Knowledge is a repository of information catered to Vietnamese youth leaders. The documentation lists helpful guides for many functions of UNAVSA. The documentation can be accessed by using the search function on each page or you can just throw your computer across the room where unicorns will use their rainbow powers to turn it into magical candy which, once consumed, will make you a level 70 computer ninja.
Are you awake now? Good.
That paragraph sounds like a boring lecture, at least until the unicorns show up. Using humor and emotion (SURPRISE!) are some of the techniques we can use to engage people. These techniques, which I’ve listed below, all aim to get your brain to pay attention by recreating what this interaction could be if it were happening in person. When we do that, information is easier to understand and remember.
- Conversational writing style – Use an informal, active style similar to the way you’d speak to someone in person.
- Humor and emotion – Using humor is great but it’s sometimes hard or impossible to localize. Emotions like surprise and “I didn’t know that!” (not sure what to call that emotion) might be easier to include.
- Multiple learning styles – Just like in school, people learn differently. Also, everyone benefits from seeing the same content expressed in multiple ways.
- Repetition – When you explain something in a different way with different media, you’re also, obviously, repeating it which is another good way to help people remember what’s important.
- Images and video – Using images and video to explain things along with text is not only the next best thing to being there to help in person, they are an easy way of including multiple learning styles and repetition.
- Activities – Especially in a tutorial, it’s good to give people something useful to accomplish. It’s one thing to read instructions and understand the process but it’s often helpful to remind people to try things out.