Top 6 tech comm trends for 2013

Flexibility in several dimensions is my tech comm mega-trend of the year, after mashing up the top 6 trends presented by Sarah O’Keefe and Bill Swallow in Scriptorium’s annual tech comm trends session. Head on over to Scriptorium’s site to watch a recording of the webcast and to read Sarah’s take on the trends she presented.

1. Velocity

Velocity is Sarah’s first trend which simply means that we tech comm’ers are expected to create, deliver and update content faster than before. Also gone are the days – or months – when localized documentation could be several weeks late.

If we are serious about this, we need to revamp our documentation processes. I agree with Sarah: A recent restructuring of documentation processes has sped up my throughput and made my estimations more predictable. So it has improved my productivity as a whole.

It’s also made me more flexible because my smaller task packages take less time before I finish with a deliverable. It used to take me 4 to 6 weeks to update a user manual, so interrupting this task for something more urgent was expensive because it further delayed the manual and also clogged up my pipeline. Now I take about 2 weeks for the same task which allows me greater flexibility in sequencing my tasks because I still have a chance to finish the manual by the end of the month, even if we decide that I first spend a week on something else. I could not have achieved this  flexibility without revamped processes to analyse and specify documentation and without a topic-based approach.

2. PDF is here to stay

Bill’s doesn’t see PDF go away any time soon, if only because it’s durable, controllable, reliable and downward compatible to that other durable format called print-on-paper. Google Docs might be a potential competitor, but Bill doesn’t see it making great advances on PDF in 2013.

As comments from the audience showed, there seems to be a lot of passion about the issue and some people can’t seem to wait to lay the last PDF to rest, finally. As a tech writer in semi-regulated industries, I know that I’ll be creating PDFs for my users for a looong time. It might not be a trend per se, but I agree with Bill that we haven’t seen the end of PDFs just yet.

3. Mobile requirements change technical communication

Mobile will be the big game-changer for tech comm this year, predicts Sarah. Requirements for mobile documentation mean that PDF will be one format of many – and maybe not the primary one in many cases. Other essential deliverable formats include HTML5 (for an online audience) and apps (for native or offline use).

The limited real estate of mobile devices requires more flexibility in how we structure and present documentation. Progressive disclosure can help us to integrate essential user assistance in labels or pop-ups. Beyond that, we need a strategy of what to disclose where and how to create a seamless and consistent user experience.

4. Mobile drives change

Similar to Sarah’s trend, Bill underscored the influence of mobile documentation. He emphasized the need for concise, no-frills content. Rather than jump on the progressive disclosure, Bill presented an alternative scenario: An “executive” device with the main product hooks up with a second, mobile device which presents the corresponding documentation. (I didn’t quite understand this point, I think Bill mentioned a second screen embedded in the primary device, but I’m not sure.)

5. Localization requirements increase

Bill sees the scope of localization expand as the need for translation no longer stops with external documentation. Increasingly, internal documents also need translations because corporations need to keep international teams afloat and cannot afford to lose traction due to vague or misunderstood communication.

This is also the reason why, economic advantages notwithstanding, machine translation hasn’t taken off yet. But a hybrid process seems promising in some areas where machine translations become useful and reliable after human editing. Enter flexibility as our audience now might also include far-flung colleagues – and our tasks might include editing text that’s been translated by robots.

6. Rethink content delivery

As we face diverse requirements for working at different speeds in more formats and for more diverse audiences, we need to be flexible and rethink what we deliver and how. With demands like these, pages of static contents are frequently not sufficient. Instead, users need more dynamic content and filters to customize the documentation to what they need at the moment.

Someone in the audience summed it up very well: “Think of content as a service, not a product.” To me that makes a lot of sense, because it emphasizes the recipient of that service and their situation over the static dead-on-arrival quality that comes with a tome of printed pages.

My summary

I think flexibility is a key ingredient in many of the trends Sarah and Bill discussed with the audience. The recent opportunity to reorganize how I create documentation has given me two kinds of confidence: I have a suitable process in place for now. And I can change processes and methods when I need to.

A secondary trend occurred to me as well: Thanks to Sarah’s spirited mc’ing by which she included the majority of audience questions and comments, this webcast felt a lot more communal than previous ones I have attended. It was almost like single-session, virtual mini-conference. And if industry leaders can bring us together outside of conference season, we can strengthen our networks and move our profession forwards – with just a little bit of flexibility.

First day at tekom12

This is my second year at tekom, the world’s largest tech comm conference held annually in Wiesbaden, Germany. tekom is nominally a German conference that coincides with its international sibling conference tcworld in English. As the hashtag confusion on twitter shows once again, the English tech comm scene tends to use both names. (Which makes me wonder why the organizers don’t simply use the tekom name for the whole thing which has sessions in English and German…?)

My session on meaning in tech comm

I skipped the morning sessions, since I was feeling a little under the weather. I didn’t even get to tekom until around 1 pm, but in plenty of time for my own presentation on How our addiction to meaning benefits tech comm. I had submitted two very different talks, and I thank the organizers that they picked the “wacky” one. And to my surprise, I had about 100 people interested in meaning, semiotics and mental models! I thought the talk went well. I had some nice comments at the end and some very positive feedback on twitter afterwards.

You can find my slides on Slideshare and on the conference site. Sarah Maddox has an extensive play-by-play write-up of how my session went on her blog.

Content Strategy sessions

Scott Abel has put together a very good stream of content strategy sessions, where I attended the presentations of Val Swisher and Sarah O’Keefe (I also blogged about Sarah’s presentation). I’m not sure if my observation is accurate, but it seemed to me that there was less interest and excitement about this stream this year than at the premiere last year. As befits content strategy, both sessions I attended were strategic, rather than operational, so they dealt primarily with how tech comm fits into the larger corporate strategy.

Marijana Prusina on localizing in DITA

Then I went to hear Marijana Prusina give a tutorial on localizing in DITA. I have no first-hand experience with DITA, but I use a DITA-based information model at work, so this gave me a reality check of what I was missing by not using the real thing. Seeing all the XSLT you get to haggle with in the DITA Open Toolkit, I cannot exactly say that I regret not using DITA.

Beer & pretzels

Huge thanks to Atlassian and k15t who sponsored a reception with free beer & pretzels – and even t-shirts if you left them your business card. This coincided with the tweet-up. It was good to see tech comm colleagues from around the world (Canada, the US, Australia, France and Germany, of course). Some I had known via twitter or their blogs for a while, so it was a welcome chance to finally meet them in person.

- For more, many more session write-ups check out Sarah Maddox’ blog!

- So much for the first day, two more to come. I’m looking forward to them!

Scott Abel on Structured Content at TCUK12

Scott Abel delivered his keynote It’s All About Structure! Why Structured Content Is Increasingly Becoming A Necessity, Not An Option in his usual style: Provocative, but relevant, fun and fast-paced (though he said he was going to take it slow). He even channeled George Carlin’s routine on Stuff: “These are ‘MY Documents’, those are YOUR documents. Though I can see you were trying get to MY Documents…”

His style doesn’t translate well onto a web page, so I’ll restrict myself to his 9 reasons Why Structured Content Is Increasingly Becoming A Necessity:

1. Structure formalizes content, so it can guide authors who need to make fewer decisions when writing it. It also guides readers who can find more easily where the relevant information is in the whole documentation structure or within a topic. And it guides computers which can extract relevant information automatically and reliably.
2. Structure enhances usability by creating patterns that are easy to recognize and easy to navigate with confidence.
3. Structure enables automatic delivery and syndication of content, for example, via twitter – and you’ll be surprised occasionally when and how other people syndicate your “stuff”.
4. Structure supports single-sourcing which means you can efficiently publish content on several channels, whether it’s print or different online outputs, such as a web browser, an iPad or a smartphone.
5. Structure can automate transactions, such as money transfers, whether they are embedded in other content or content items in their own right.
6. Structure makes it easier to adapt content for localization and translation, because you can chunk content to re-use existing translations or to select parts that need not only be translated but localized to suit a local market.
7. Structure allows you to select and present content dynamically. You can decide which content to offer on the fly and automatically, depending on user context, such as time and location.
8. Structure allows you to move beyond persona-ized content. This is not a typo: Scott doesn’t really like personas. He thinks they are a poor approximation of someone who is not you which is no longer necessary. With structured content (and enough information about your users) you can personalize your content to suit them better than personas ever let you.
9. Structure makes it much easier to filter and reuse content to suit particular variants, situations and users.

TCUK12, day 1: Workshops & company

The first day of the ISTC conference TCUK12 offered workshops and great opportunities to meet tech comm’ers from all walks of life and many corners of the earth.

When I arrived late on Monday evening, I promptly headed for the bar and joined the advance party for a last round – which lasted so late that I’m not even sure in which timezone it was 2 am before I turned in…

Robert Hempsall: Information Design 101

Robert Hempsall offered a great and engaging hands-on Information Design 101 workshop about information design. The workshop focused on the five key areas of content and structure, language, layout, typography, and lines and spatial organization. Using a formal application to vote in English elections by mail, Robert led us through the process of designing the form to maximize clarity and usability.

Thanks to our versatile and engaged group of delegates, our work on the form was not only lively, but showed how different disciplines contribute to the solution of better information design, from tech comm (with its principles of minimalism and parallelism) via user interface design (with its emphasis on making completion of the form as easy and painless as possible) to graphic design.

In this sense, the workshop presented a good example of “design by committee” (which is usually a terrible idea): We discussed the most intuitive and user-friendly sequence of the form’s elements and how best to phrase the section headings, as questions or as imperatives. A seemingly innocuous “all of the above”  check box also caused a debate: Should it precede the individual options, to make completing the form quick, easy and painless? Should it come last, so users hopefully first read and reflect on the options? Or should it be omitted altogether, so users have to think about each option and select all that apply.

Form design is maybe not among the core tasks for many tech writers. Yet I’ve found several challenges in it that are strikingly similar to getting a topic structure just right, whether it’s a consistent, indicative heading, good, clear instructions or logical structure.

Rowan Shaw: Quality Across Borders

Rowan Shaw‘s workshop Quality Across Borders: Practical Measures to Ensure Best-Value Documentation in Global Technology Businesses focused on creating documentation both with authors and for users who have English as a second language (ESL).

As in introduction, Rowan presented us with 10 sentences each of which had some element that can create a problem for ESL readers, ranging from “10/03/12″, which could mean 3 October or March 10, to metaphors and slang.

If you need to hire ESL authors, it can be helpful to ask applicants to sit for an exam which tests skills such as procedure writing, fluency of expression, structuring, detail, consistency – but also their motivation for applying, to spot those candidates who want a foot in the door, but might not be interested in tech comm in the long term. We discussed a sample test, whether it was applicable and appropriate in all cultures.

Rowan suggested that, given the practicalities of global ESL authors, you might have to settle for less than perfect profiles in candidates. Then it is important to know which skills are easier to teach someone on the job, for example, grammar, structuring, capitalization, punctuation and how to use a style guide. Other skills are harder to teach, such as an eye for detail, audience orientation, logical thinking, but also more intricate language skills, such as prepositions and correct modifiers.

Again, this workshop benefitted tremendously from the diverse talents in the room and the experiences delegates brought to the topic.

The right company

I keep harping on how much I enjoy and benefit from meeting other tech comm’ers. Just on the first day:

• I found that several other doc managers are also wary to hire subject matter experts, who are less committed to tech comm, because they might just want a foot in the door (see above).
• I had an immensely helpful conversation with someone who’s a visiting professor and who could give me tips and ideas that I can try as I consider teaching as a future path.

So day 1 was very fruitful already, and I’m looking forward to more sessions and conversations to come.

TCUK12: Internationalisation as an accessibility issue

Addressing internationalisation and accessibility issues are two complementary ways to make technical communications (as well as products and web sites) more inclusive. Attend a panel discussion at TCUK in October to find out what pitfalls internationalisation and globalisationcan bring and what others have done to address them.

The panelists

The panel brings together four internationally experienced technical communicators:

• Karen Mardahl is TCUK’s keynote speaker of this year’s accessibility stream. She believes in encouraging technical communicators to develop their skills and knowledge to strengthen their role in any organisation, but especially to do their part in making products and services more inclusive for all people. Living and working in Denmark, she has experienced the subtle challenges of negotiating technical communications in an international, intercultural context first-hand.
• Robert Hempsall is a specialist information designer whose international clients, such as international airlines and telecommunicartions companies, require forms, bills and letters designed for efficient localisation and maximum accessibility.
• Ray Gallon is currently an independent consultant, specializing in the convergence of user guidance and usability for international companies such as General Electric Medical Systems, Alcatel, and Ilog-IBM. Ray is currently a member of the international board of directors of the Society for Technical Communications (STC) and past president of the STC France chapter. He shares his life between the Languedoc region of France and the city of Barcelona, Spain.
• I will be moderating the panel and insert the occasional anecdote or lesson learned from my experience of 13 years of writing software documentation in English that is accessible and useful for users all across Europe.

The topics

The focus of the panel will be a dimension which frequently shuts out wide ranges of customers and users: National borders and the languages and cultural conventions they denote. Internationalization is an accessibility issue in user interfaces and documentation. In several ways, it affects whether you can reach your customers and how well.

For example, in documentation (and user experience design as a whole), language can be:

• Inclusive when it is comprehensible to customers who speak English as a Second Language
• Exclusive when it relies on specific cultural conventions, idioms or references, including common items, such as date and time Readability can be

The presentation of examples and entry forms can be:

• Inclusive when they support different international conventions
• Exclusive when they are limited, for example, to 5-digit zip codes

How to distinguish corresponding strategies?

• Localization: The adaptation of product and documentation to a specific market, a locale.
• Internationalization: The presentation of product and documentation that enables efficient localization in different cultures and languages.

Our panel discussion discusses these issues and more with examples and suggestions how to make technical communications more inclusive in terms of language and culture and hence more successful internationally.

If you know additional questions or topics of internationalisation as an accessibility issue, please leave a comment.

Improve tech comm by knowing a foreign language

Knowing a second language can help your tech comm work in a couple of ways. The benefit is probably not great enough in itself to justify learning a language, but if you have or had other reasons, it’s worth to consider these side benefits.

Making decisions in a foreign language

I got to think about this when I read a story in Wired that “thinking in a second language reduced deep-seated, misleading biases”. Psychologists at the University of Chicago conducted a study (abstract, full text in PDF) that asked “Would you make the same decisions in a foreign language as you would in your native tongue?”

In a foreign language, we use the same experiences and processes to evaluate situations and estimate risks. However, “a foreign language is like a distancing mechanism. It’s almost like you’re a slightly different person,” says Boaz Keysar who led the study (Business Week). According to the study, thinking in a non-native language emphasizes the systematic, analytical reasoning process. Thinking in our native tongue, on the other hand, leaves more room for the complementary intuitive, emotional decision process: “The researchers believe a second language provides a useful cognitive distance from automatic processes, promoting analytical thought and reducing unthinking, emotional reaction” (Wired). (Whether an analytical process yields “better” decisions is an entirely different story…)

Making tech comm better with a foreign language

For the past 12 years that I’ve worked full-time as a tech writer, I’ve written almost exclusively in my second language English, though I did occasionally translate my English writing into my native German. The study’s conclusion that a second language provides a “useful cognitive distance … promoting analytical thought” explains what I’ve experienced in my work in either language, beyond the limits of actual study:

1. A second chance to learn how language works. Many writers I’ve talked to have a solid grasp of their native tongue, but cannot necessarily explain the rules why something is right or wrong. When you learn a second language consciously, you also learn about grammar (again), its powers and limitations. And you can understand how something what works in one language can be similar or even different in another. For me, writing in English certainly made me a more conscientious “grammarian” in either language.

2. Mirroring the “distance” of users. In my experience, the distance that a second language brings is basically pragmatic incompetence: In a foreign language, I’m not as fully aware of the social context, of how time, space and inferred intent contribute to any communication act. I may trip over an idiom I don’t understand, or I may fail to see the irony of a statement and take it at face value.

In tech comm, this linguistic challenge is actually a benefit, because many of my readers share in that distancing experience. My readers may read my documentation in their second language. Or they might use the product in a context and for a purpose that is more or less different than intended and documented. This is why localization is harder than just translation. Internationalization can even become an accessibility issue, when a product no longer works properly in a certain context. So facing similar pragmatic uncertainties makes me a better advocate of the users I write for.

Your turn

If you know a second language, do you find it helps your writing? Do you have other reasons or benefits beside the ones I listed?

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.

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

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?