2nd day of sessions at TCUK 13

The business and managing of tech comm was the predominant topic of my TCUK13 experience, as I reflect some more on the sessions I attended and the conversations I joined.

A. Westfold on collaborative authoring in DITA

Andrew presented a case study of McAfee over several years, from separate product teams and “artisanal”  lone writers to a larger, unified team of writers collaborating in DITA. During this time, McAfee also grew by acquisitions which meant that additional writers, methods and tools came on board. Here are the most essential stages of their journey:

1. Improve several individual procedures for quick wins: Single sourcing reduced translation efforts. Automating the translation round-trip cut out costly manual layout efforts.
2. Move to topic-based authoring: They chunked up content into topics and moved them into DITA to validate the topic structure. (It turned out that many task topics could not be automated and essentially had to be rewritten in valid structure.)
3. Bring in a content management system to reap the full benefit from single sourcing and topic-based authoring. This helped to reduce the number of redundant topics and to make localization even more efficient.

While their journey is far from finished, McAfee has realized the following benefits so far:

• Easier administration of topics than of larger content chunks before. It’s also easier to solicit reviews for smaller stand-alone chunks.
• Faster, more consistent creation of deliverables for several product variants thanks to better use of standard templates.
• Documentation processes align well with recently introduced agile development processes.
• More efficient, streamlined workflow thanks to better integration between documentation and localization.

I really enjoyed Andrew’s presentation. It showed that projects to improve tech comm do work out, even if you don’t always see past the next stage, and you may have to adopt due to other changes in the company.

A. Warman on “Managing accessible mobile content”

Adrian Warman from IBM hooked up two important tech comm issues, accessibility and documentation for mobile, into a survey session.

Accessibility makes it easier for everyone to fit in, participate and contribute, irrespective of disabilities. In short, it ensures that a user’s disability does not mean a personal disadvantage. For tech comm, this means that sufficient documentation is accessible. For example, if your online help in HTML is accessible, it’s not necessary to make the same contents in PDF accessible as well – or vice versa, as the case may be. Adrian advised us to keep an eye on “EU mandate M 376” which may soon make some level of accessibility mandatory for products traded within the EU.

Mobile (smartphones and tablets) for tech comm means not just a technology, but an expectation, a mindset. It’s more than simply fitting our output onto smaller screens. Its different dimensions of interactivity, such as progressive disclosure and user-generated content, challenges us tech writers to re-think how to best convey an idea. Which is the best taxonomy that supports both, mobile devices and accessibility?

I don’t think there was a lot of new, revolutionary content here, but since I haven’t dealt much with either topic so far, it was a welcome introduction that was concise and well presented.

E. Smyda-Homa on useless assistance

Edward reported on his twitter project @uselessassist where he “Retweets to remind organizations of the frustration and negative emotions that result from poorly prepared assistance.” He presented many examples of poor user assistance. Some people complained about insufficient instructions, whether they had not enough images or only images. Some found the instructions too long (“I know how to prepare toast!”) or too short or redundant. Some pointed out typos or bad translations.

This was a very entertaining session – and you can easily get the gist of it by simply looking up the account or following the twitter feed. It’s anecdotal evidence in real-time that users actually do read the manual – or at least try to.

While every tweet is heartfelt, I think not every one merits a change in the documentation – if only because some are contradicting each other. But I find Edward’s project very enlightening and nodded to myself in embarrassed recognition a couple of times…

– Feel free to leave comments about any of the sessions, whether you have attended them or not.

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.