Auditing Documentation and Processes at tcworld11

Auditing your documentation, and your processes, can help you to gauge estimates and issues as you prepare for localization or content migration. That’s what I learned in Kit Brown-Hoekstra’s useful 2-hour workshop at tcworld (tekom’s international half).

You can easily do the audit yourself: Take a little time, step back from your documentation, and identify weaknesses and areas for improvement. Acting on your audit results, you can

• Improve customer satisfaction
• Decrease localization costs
• Establish a baseline and a direction to develop your documentation
• Calculate costs and benefits of changes

If you don’t have an express mandate for the audit, it can be worth it to do sort of a “draft audit”. It may come out a little patchy in places, but I think it can give you a first idea of where you stand. With the initial results and measures you can more easily get the time to do an in-depth audit. (But don’t be surprised if colleagues or managers hold you to the improvements you’ve uncovered… :-))

What to audit

The organization level

Perform a strategic SWOT analysis of Strengths, Weaknesses, Opportunities and Threats of your role in your organization. Internal strengths and external opportunities (mainly) will give you useful arguments to get buy-in from management for changes and further developments you plan. Internal weaknesses and external threats (mainly) help you to assess and manage risk as you proceed.

• Strengths, for example, may include technical expertise and an understanding of user needs and tasks.
• Weaknesses, for example, are poor self-marketing or resistance to change.
• Opportunities, for example, can include agile development (which gives writers a better position in the process) and social media (if you adapt to them and moderate augmenting user-generated content).
• Threats, for example, might be smaller documentation budgets or social media (if you do not adapt or cannot keep up with user-generated ontent).

Note how threats can be turned into opportunities, if you tackle them wisely! Or vise versa…

The process level

Assess your documentation process through all stages:

Requirements > Design > Writing > Review > Edit > Localization > Publication > Feedback > Modification > Deletion

Answer the following questions:

• Are all stages well-defined?
• Is it clear when and how you get from one stage to the next?
• Do all participants in a stage know what to expect and what to deliver?
• Can you measure the success of your process?

For the sake of an efficient process, imagine each hand-over between participants or stages as an interface and try to define what’s handed over when and how as well as possible.

The product level

Identify qualities and issues of the product you document to distinguish them from those in your documentation. Weaknesses in documentation often mirror weaknesses or issues in the product, e.g., a poorly designed user interface or a workaround that’s required to complete the user workflow.

You need to know about these issues separately, because they hurt your documentation, but you usually cannot fix them yourself. You can only supply band aid.

The documentation level

Assess the structural quality of your documentation (not the quality of a manual or each topic). Answer these questions:

• Do you have a suitable information model? This is an architecure that defines the structure of your documentation on the level of deliverables (such as a manual or online help) and on module level (such as a topic or a section).
• To what extent does your documentation comply with that information model?
• Do you write documentation so the topics or sections are reusable?
• Do you reuse topics or sections to the extent that is possible?
• Do you write documentation so it is ready and easy to localize?
• Do you use standardized sentences for warnings and recurring steps to minimize localization efforts?
• Do you leave sufficient white space to accommodate for “longer” languages? For example, German and Russian require up to 30% more characters to say the same as English.

Also assess the content quality of your documentation (now look at some manuals and topics):

• Is it appropriate for your audience and their tasks?
• Is it correct, concise, comprehensible?
• Remember to audit localized documentation, too.

It’s usually enough to audit 10-20% of them to spot 80-90% of the issues.

Audit for efficiency

• Be objective. …as objective as you can, if you’re auditing your own documentation.
• Collect issues. You can use a simple spreadsheet to collect your findings: Enter the issue, its impact, its current cost, and the cost to fix it.
• Prioritize improvements. Ensure that a lower future cost makes the improvement worth doing, after you’ve added up the current cost and the cost to implement the improvement. Start with changes that cost the least and will save you the most.

Bonus tool

To really dive into quality assessment of your documentation, you can totally combine Kit’s audit process with Alice Jane Emanuel’s “Tech Author Slide Rule” which focuses on content quality. Use both and you have a good handle on your documentation – and more improvement opportunities than you can shake a stick at!

Your turn

Do you find this helpful to audit your documentation? Do you know a better way? Or do you think it’s not worth it? Feel free to leave a comment.

Advertisement