According to a poll we set up among the techcomm people, successful update of user manuals is among the most troublesome areas of help authoring. What you need to understand is that building reliable and clear processes for documentation maintenance is the key to success here. This article will explain how to set up the documentation updates right from the very beginning.
Divide and Conquer
If it is possible to divide technical documentation into areas (can be products or product areas) and assign these to people permanently, that can help with update quality.
Your documentation team is going to have dedicated experts covering all the data. The quality and speed of update will grow as tech writers won't be overflooded with information. Instead, each will have their own area of responsibility where they will feel confident. Also, this will create more stable cross-team communication - devs or support, or whoever, will know for sure who to ask about certain help topics.
What's important to remember is that there has to be a backup. If you have only one person on the team who knows, let’s say, how to write the docs for the mobile version of your software, then what happens when they go on vacation? Make sure that each area is covered by at least several tech writers. This way you won’t have to teach everybody everything and have a robust workflow.
Prepare User Manuals for Maintenance
Any action you take should be weighed out. This might sound like a lot, but thoroughly considering the consequences is what it takes to be proactive. Technical documentation consists of building blocks that repeat and reiterate themselves all the time. Reusing them properly is what brings great results.
I mean, tech writers’ burn-outs caused by the need to fix one sentence in twenty help topics each release must stop. With all the awesome tools that we have now, these manual efforts are nonsense. With software for help writers you can leverage content reuse and take a lot of stress from the team. Consider the following single-sourcing techniques:
- Variables. A lot of things can be turned into variables in a user manual. Product and build versions, contact info, company name, etc. Later you will need to change the variable and the content is going to be automatically updated.
- Content Snippets. This is a surefire way to maintain chunks of data placed anywhere in your documentation project. Add steps, instructions, warnings, and any other repeatable content with content snippets. Change the source - everything gets updated. Win!
- Conditional Content. You can reuse all types of content which not only saves maintenance time, but also allows creating multiple outputs from one source. Here’s what can be conditioned in ClickHelp: topic content, styles and scripts, and even the TOC. These are easily managed with the help of output tags, read more here - ClickHelp - Single-Sourcing Techniques.
Improve Communication Channels
Technical writers are no devs. They often need insights from subject-matter experts. And, this interaction should never be spontaneous. SMEs may not be available for advice 100% of time when you need it ASAP. Or, the way they transmit information may not be perfect. These things need to be settled, this is crucial.
For example, some SMEs like to explain things in writing, which is great, but sometimes jumping on a quick call is better. Or, a contrary situation - your SME likes to explain things on calls but is reluctant to write them down which makes it so much harder to review data. That’s why you should figure out how communication with SME can be made more productive and follow through with it beforehand.
Conclusion
This is our take on making documentation updates easier. A lot of focus should be put on building the right foundation and this allows simply straightening the details up going forward. Are there any other specific things that you are doing to make maintenance smoother? We will be glad to hear your ideas in the comment section below.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices