I've written a series before that emphasizes the importance of maintaining a clean, up-to-date knowledge base (Part 1, Part 2, and Part 3). Before you clean the knowledge base, though, there must be content worth cleaning. After all, there's no need to clean the house if there isn't any furniture in it. There is a lot that goes into writing an effective ServiceNow knowledge article, and following these 7 steps should get you started in the right direction.
1. Slow Down!
Note that the first step doesn't say "start writing." In fact, I don't recommend writing until step 5. Step 1 is to slow down, and don't start putting pen to paper just yet (or hands to keyboard). You may think that you have an idea in your head of what you want to write, but without a clear roadmap, it's easy for an article to get sidetracked from its original purpose. So slow down; good writing takes time. If you rush past the planning steps, the quality of your article will suffer.
2. Identify Your Audience
This is an often overlooked, but important, aspect of technical writing. Ask yourself the following questions: Are you writing for a technical audience, or a more general audience? What technical expertise will your readers have? Will your audience understand acronyms or other technical jargon?
Oftentimes, writers will assume that the audience has the same background knowledge as they do, which may not always be the case. It's also important to note that your audience may not be homogenous. You may have an audience that has different experience and/or background knowledge.
You don't need to explicitly mention your audience in your article, but it is worth writing down in your outline to make sure you've really thought about it. If you're a knowledge admin, it may be useful to include a template that prompts authors to explicitly identify the audience they are writing for to ensure the authors are actually considering their audience.
3. Identify Your Objective and Scope
Scope creep doesn't just happen in software development! The same way that you would carefully define requirements before developing software, it's important to identify the objective and scope of your knowledge article to prevent the article from diverging from its intended purpose.
One tip to help keep your article focused is to take advantage of the other articles in knowledge base. If there are relevant side topics, include a link to another knowledge article instead of including details that derail the original focus.
4. Create an Outline
Now that you've identified the audience and the boundaries of your article, you can begin to create an outline for your article. Again, it might be tempting to just start writing, but without an outline, it can be difficult to maintain the objective, scope, and focus of your article. The outline is the scaffolding that helps you properly build out your article.
You should look to see if your organization has a preferred outline. At my Fortune 500 client, we advised the knowledge admin to use the default text to give a basic outline for users who are creating a knowledge article. By including an outline with directions, you can help users to organize their articles in a consistent manner across the knowledge base, improving both the writing and the reading experience.
Default Text Used as An Outline
5. Write the Article
Now that we're at step 5, we're finally going to start writing. If you followed all of the preparation steps, this step should be fairly straightforward now. Use the scaffolding from your outline, and fill in the relevant details and information while continuing to stay on topic, and considering your audience throughout your article. Here are some suggestions for a well-written article:
Keep Your Writing Simple (i.e. Technical Writing 101)
- Use the active voice when possible. The passive voice has its time and place, but for technical writing, you generally want to write in the active voice.
- Remove the fluff - remember, you're not in college where you might have a minimum number of pages to fill. In fact, you have the opposite constraint: a limited attention span of your reader. Respect your readers and keep your articles concise.
- Keep your sentences short. The complexity of technical subjects can cause sentences to become run-on sentences so consider splitting sentences up if they get too long.
- Use lots of white space! Headers, sub-headers, and bullet points can help you to both maintain the structure of your outline and make your article more readable.
- Screenshots or other relevant pictures are incredibly helpful for clarifying technical articles.
- Be sure to include captions to make sure readers know what the screenshot is displaying.
Link to Other Articles as Relevant
- As mentioned earlier, linking to other articles can help you stay on topic while providing additional context as needed.
- Tying articles together can help create a web of knowledge that makes your knowledge base exponentially more powerful for your users.
- If you are maintaining a clean knowledge base, you will be able to link without fear of articles becoming outdated, or links becoming dead.
Before sending your article through the official review process, review it yourself. If possible, try to get someone else to review the article as well. The more sets of eyes on your article, the better. As an author, remember that once your article is published, it's not a conversation. You can't clarify any questions that the reader has. So if anything is unclear in the article, try to identify it now and get it cleared up.
Once you've conducted a personal review, it's time for the article to go through your organization's review process. Incorporate any feedback, and get ready for the final step: Publish and Maintain the Article.
7. Publish & Maintain the Article
At this point, your article should be ready for primetime. Publish the article to the knowledge base. Be ready to maintain the article - I've written before about the importance of maintaining a clean knowledge base. In order to keep your organization's knowledge base clean, incorporate feedback, and update the article if it becomes outdated.
In my first two blogs in my series (Part 1, and part 2), I discussed the importance of maintaining a high quality for all articles in your knowledge base. It can be tough to get users to appreciate the importance of the knowledge base, but if you can gain buy-in, this guide can help users to write the high quality knowledge articles that will make your knowledge base successful.