How to keep your documentation up to date
One of the major concerns we hear from people is, "How do I keep my documentation up to date?" Here are some simple strategies to make it simple to keep things current in your documentation.
There are a lot of complicated solutions for keeping your documentation up to date. But we have found that complicated solutions rarely work. Here are three simple suggestions.
- Separate concepts and tasks
- Use pictures in your documentation
- Make sure your support team uses your documentation
- Tag articles
If you mix concepts and tasks into the same article then updating your articles will be difficult. Concepts are articles that deal with the following questions:
- Why you would use a feature
- When you would use a feature
- Why a feature is designed the way it is
Tasks answer one question:
- How to use a feature to create a desired output
Concepts won't change as quickly as tasks will. If you separate your concept and task articles out you will find that keeping both up to date will be simpler.
What? Pictures can make updating your documentation simpler? Impossible.
Actually, it is very true. If your documentation doesn't use pictures then guess what you have to do to see if an article needs updating? You have to read it. And that takes time.
If you use lots of pictures then you can simply scan the article. You will be able to quickly notice screenshots or procedures that need to be updated.
-- Begin shameless plug --
Now, updating screenshots in documentation can be a real pain if you don't use the right tools. ScreenSteps makes replacing screenshots simple and fast so if you are worried about keeping your docs up to date then you might want to check it out.
-- End shameless plug --
If your support team doesn't use your documentation regularly to answer customer support questions then it is going to be really hard to tell if something is out of date. Your support team has the most immediate contact with customers. If they are pointing your customers to existing knowledge base articles on a regular basis then they will find out right away if something needs updating.
Use your documentation with your customers and your docs will stay up to date for the following reasons:
- Your customers and support agents will let you know right away when something is out of date.
- Your support agents will demand that you update the content because they need up to date information to do their job effectively.
Tagging articles involves a little more work so only do it if the previous suggestions aren't sufficient for your situation. Any decent online knowledge base product is going to allow you to tag articles in some way. By tagging articles based on areas or screens in your application you can quickly find articles that will be affected when a change is made to your application.
Like I said, this can be a bit more complex. We have found that using pictures and using our documentation on a regular basis is enough for our organization. But some of our customers find that they need to tag articles as well. If you are going to take this approach here are some suggestions:
- Standardize your tags - Make sure your entire team is on the same page with your tag structure. If everyone is using different tags then they won't be much use to you.
- Don't get too specific - While it might seem like a great idea to tag every detail of a lesson this quickly bogs down the authoring process. Start with general areas of your application, for example, major screens, tags or functional areas. If you find that you need more specificity it is easy to add it later. But don't get bogged down early on.
- Be realistic in your expectations - Tags are not going to be able to completely automate the updating process. They are meant to be a help, not a comprehensive solution. So don't worry about perfection in your tagging strategy. Just ask yourself the question, "Is tagging helping our team update our documentation with less effort?" If the answer is yes then keep doing what you are doing. If the answer is no, then modify your strategy.
What do you do if you are delivering content in a format that doesn't support tagging, for example, PDF or Word files? Just make sure you use a documentation authoring tool to tag help articles in your authoring environment.