Writing how-to guides and product documentation seems like it would be an easy task. But most support and documentation managers quickly find managing documentation is a real headache.
What begins as an informal process of writing FAQs and knowledge base articles quickly becomes a disorganized mess:
-
The articles you really need aren't getting written
-
The articles you have are out of date
-
You have no process for creating or curating your content
So we thought it would be helpful to share our process for creating help articles.
The 5 Stages
Each article in your knowledge base has to pass through 5 stages:
-
Determine the topic
-
Assign the author
-
Capture the knowledge
-
Polish and publish the article
-
Maintain and improve the content
The stages aren't meant to prolong the writing process - rather, it's meant to help you organize a workflow that gets helpful articles written, and in the hands (or on the screens) of your customers.
1. Determine the topic (ie decide what to write)
As we speak with documentation authors, this is the single biggest obstacle to creating knowledge base content: deciding what to write.
It seems like it would be so easy, but in reality it can be quite challenging.
Many companies take the approach of documenting the features of their product. This is a big mistake. Your customers don't purchase features, they purchase outcomes. The job of your documentation is to help your customers achieve the outcomes they desire with your product.
One of the most effective ways to determine "what to write" is to look at the questions your customer support team is receiving. Each "How do I..." question can become a knowledge base article.
This is a very quick and effective way to determine what to topics to write about. Plus, you know the articles will be useful because they answer questions your customers actually have.
2. Assign the author
The next step is to figure out who will write it. We see a lot of companies that have a list of knowledge base articles that need to get written, but they never get around to writing them.
No one really owns the responsibility of writing the content so it never gets done.
When a new article needs to be written, quickly determine who is going to be the best person to write it. Sometimes that might be a technical writer or support manager on your team. Other times the subject matter may require that an implementation manager or developer write the content.
Realize that this is only the first draft, not the final one. The important thing is to get the knowledge out of the author's head and into a document that can later be polished.
This is one of the reasons we added the concept of document owners in ScreenSteps. We can easily assign a draft article to an author so that it is clear who is responsible for writing the content.
3. Capture the knowledge
Too many people start writing, editing and polishing the article all at the same time. We have found that this really slows down the process. If you can focus on capturing the knowledge first then you accomplish two things:
-
You ensure that your article will be accurate
-
You can separate the knowledge capture and editing process, making it easier to keep the authoring process moving.
How you capture the knowledge will differ depending on whether you are familiar with the topic of the article or whether you need to go to someone else to get that information (for example a product manager, support agent, or developer).
For "How do I..." type articles we have found two ways to be effective:
-
Use an application like ScreenSteps to capture each step of the answer as an image. By capturing each step as an image you ensure that the answer is complete and correct. Since you have to walk through the process to capture the images, you are prevented from leaving anything out.
-
If the person who has the knowledge doesn't have access to ScreenSteps or something similar then just have them record their screen. You can go back later and copy screenshots out of the screen recording to document the process.
The important thing is that the knowledge gets captured in a way that ensures it is accurate.
If the person who understands the topic only writes down a bulleted list of steps, your customers will find that steps were left out. Using video and images at this initial stage will really improve the accuracy of your articles.
If you create a step-by-step series of screenshots it helps you think of things as a step-by-step process.
4. Polishing and publishing the article
After the knowledge has been captured, prepare the article for publication. If you used something like ScreenSteps to capture the knowledge, then it is a pretty easy task to refine it into a ready-to-publish article.
If what you received was a recorded video or a text only document then you will need to do a little work.
Recorded videos
Try to create a step-by-step outline of the video to document the process. You can even capture still frames from the video to outline the process. Just make sure that once the document is finished it follows a clear, step-by-step flow that your customers will be able to follow.
Text only documents
If all you have is text or a bulleted list, make sure that you walk through the process yourself if possible. You want to make sure that everything is accurate. Once again, using something like ScreenSteps at this point will be very helpful for capturing images for each step of the process and making sure the article is accurate.
And when you publish the artilce, make sure it goes into a web knowledge base. PDF versions are fine as an additional delivery option, but they shouldn't be your only delivery format. You want a web based knowledge base that your customers can search and that you can keep up to date.
5. Maintaining and improving the content
Once the article is published your work isn't done. You need to maintain and improve the content.
The first step is to evaluate how effective the document is. Go to your support agents for this. When they send the article to a customer, does the article successfully answer their question? Or do they have to have continued support interactions to help the customer out with the task?
You also need to maintain the content. Make sure that it stays up to date. You can set up a regular schedule where you review your articles to make sure they are still accurate.
Once again your support staff can be very useful here. Give them a way to flag an article as needing revision or review so that you can be notified when changes need to be made.
Happy documenting!