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.

Advertisements

Keeping your documentation stakeholders happy

Don’t forget your stakeholders and their practices as you improve and change documentation. – That was the humbling lesson I learned (once again) as I presented our revamped documentation to non-tech comm colleagues.

Reporting on progress

The company I work for currently moves its documentation towards more structured writing and topic-based authoring. We’ve already rolled out redefined processes and several topic-based user manuals, so it was an opportunity to present to  non-tech comm colleagues what we’d done already, why and how we did it, and what else was in store. I talked about topic-based authoring and how it’s chunked, task-oriented, reusable, and independent of delivery format. Then I talked about the benefits and challenges:

  • For users, topic-based help can be updated more frequently, it is easier and faster to use online, though it breaks the narrative flow
  • For everyone working on our module, it means easier contributions
  • For the company, it allows to leverage* content after one-time migration efforts

* I know “leverage” is not a verb, but there were managers present who love the word… 🙂

I thought I was pretty clever for presenting how cool the new documentation was not primarily for writers, but for users, my colleagues and the company as a whole. And it did go over well on the whole. But there was…

The thing about trains

Person reading by a track in a railroad station

The most contentious issue turned out to be an unexpected use of the documentation: Current user manuals sometimes contain flowing prose walk-throughs of sample setups with many screenshots. When they are written well, they are nice to read. And allegedly users like to print out the PDF files and read them on the commuter train.

The problem of prose

There are several problems with the narrative manuals for users:

  • They are hard to use and search in, unless you want to know exactly the one thing they are describing.
  • Any sample setup is bound to miss what they need by a little or even a lot, because our product is highly configurable (you can even customize field names in windows).

There are problems for writers as well:

  • The prose is really hard to update when functions or processes change because the narrative flow may require small or large changes in several places.
  • The screenshots take longer to update and localize than mere text.

I gave these reasons, invited colleagues to check out the manuals done in the new fashion and cited survey findings that most of our users consult the documentation when they have a specific problem, though very few actually read manuals end-to-end.

But the ultimate lesson for me was that I could focus on our mission all I want, I also need to address the change with my stakeholders not only in rational terms, but also in terms of their habits and expectations.

Your turn

Do you think the customer is always right, even if he asks for documentation that is harder to maintain and harder to use in most cases? How can you promote change among stakeholders which you are sure will benefit everyone in the long run? Please leave a comment.

Welcome to summer reruns, part 2

My blog and I are taking it a little easier towards the end of the summer.

I’ve had a wonderful time with this blog so far, and I thank each and every one of you for reading, lurking or commenting. I’ve learned a lot from your comments, and I appreciate your support! It’s been a warm summer’s breeze… 🙂

As we’re gearing up for the new season, here are some reruns from the last year or so.

Popular posts from my blog

Top 10 things that users want to do in a help system

This is one of my two most popular posts by far where I draw a parallel to a department store or a library to illustrate how customers want to navigate each one.

Reality check: Writing for scannability and localization

What happens if our nobel attempts at clear topic structures and parallel sentence structures meet head on with unsuspecting readers?

Portable apps for tech writers

This is the first post in a four-part series where I recommend free and (mostly) light-weight applications that can help any tech writer in his daily tasks.

Noteworthy posts from elsewhere

If you want to get an introduction into content strategy, I think, you could do a lot worse than reading these excellent posts:

Complete Beginner’s Guide to Content Strategy

Content Lifecycle

The extraordinary world of content strategists

The last two posts are beginnings of series, so be sure to follow the links at the end of each.

Reality check: Writing for scannability and localization

Writing documentation for usability and scannability has several effects, as I’ve recently found out.  After recapping some principles, I share some anecdotal feedback on scannable documentation I’ve written.

Writing scannable documentation

[These principles first appeared in my recent post “Do you know Time?”]

Documentation can be more successful when we make it easy on our users to use and apply it quickly:

  • Clear topic structure helps users to orient themselves and learn the lay of the land quickly
    • Separate topics by type, whether it’s concept, task or reference.
    • Keep self-contained topics short and concise.
    • Insert indicative links to related topics.
    • Imply the topic type in the heading:
      • Nouns lead in headings of concepts
      • Imperatives lead in headings of tasks
      • Names of commands, variables, etc. lead in headings of reference topics
  • Parallelism (giving sentences of similar purpose a similar structure) improves scannability, comprehension and retention.
    • Start each mandatory step in a procedure with an imperative verb.
    • Start each optional step with “Optionally”, followed by an imperative.
    • Front-load your sentences, so the beginning of a paragraph indicates what the paragraph is about.

Reality check

I’ve recently written a user manual that applies these principles. It’s a guide for implementors to set up and configure a complex, customizable workflow of about two dozen steps. In that workflow, users can first import data from several sources, then validate the data, then process it, inspect and validate the results and create reports. So I have about two dozen sections that outline how to configure each step and how to test the configuration.

Here’s some of the feedback I’ve gotten on that manual – and my comments:

The documentation is quicker to navigate and easier to read.

Thanks – that was my intention, and I’m glad that it seems to work. 🙂

All those links to related topics are giving me the run-around. I want to know how to do stuff, not turn pages back and forth!

This is a reaction to topic-based writing, and I would think it fades away once users have gotten used to self-contained topics. There is actually an advantage to this: Users may leaf around a little more at first, but overall, they’ll spend less time searching and more time finding because it’s clearer what can be found elsewhere and what can’t.

I think this makes users more confident, too: If something is missing, they can move on to other means of support quickly. It’s bad enough if the documentation is possibly incomplete, but it’s worse if users get frustrated not knowing whether information is missing or somewhere else. (That last situation sounds like Donald Rumsfeld’s “unknown unknowns”…)

The structure makes the instructions repetitive and boring.

True enough, that’s the downside. What’s easy to grasp when reading one or two topics becomes boring when you read the complete manual.

The best answer I can offer is that I’d rather be clear and concise than self-servingly funny. (Or should documentation add fun to what is essentially an arduous setup process in a professional piece of software?)

The headings look weird when translated.

Ah, yes, good point! On the one hand, the translation is neither less nor more formulaic than the original manual. On the other hand, it does look weird when the translation focuses more on conventions of the target language than on scannability.

German is about as big on nouns as English is on verbs. So an English imperative in a heading “Configure the data import step” easily becomes a noun in German: “Konfiguration des Schrittes Datenimport”. (And I do need the “step” in there to distinguish it from the non-workflow “task” – it’s an intricate system…) Imagine several parallel entries “Konfiguration des Schrittes…” in the table of contents, and you have repetitive boredom alright.

However, you can also “front-load” such headings: Write “Datenimport-Schritt konfigurieren”, and the scannable unique part comes first. Writing for scannability benefits when translators know the applied principles…

Your turn

What’s your experience? Does writing for scannability work? Do users appreciate it? What issues have you encountered when localizing structured or fomulaic writing?