Ray Gallon’s Hairball of Content at TCUK12

Ray Gallon‘s session The Hairball of Content was a high-level tour de force where he argued that we technical communicators do much more than just technical writing. However, we rarely get credit for all the other work we do in tasks such as content strategy, user interface design, information architecture, etc.

Assisting the user

Our overarching task is to assist users by translating the functional thinking of engineers into something that users can act upon and experience. That means our content is not just in the documentation, but it’s also in the user interface, in the error messages, etc. So technical communications accompanies the complete design process – and we tech comm’ers need to be involved from day one.

If we take our role as the users’ advocate seriously, we need to tweak some of our dogmas a little to ensure that users get the maximum benefit.

Embedding fosters knowledge

Concepts as documentation content are not an end in itself, but they need to offer decision support to users. A concept should tell readers whether they are looking at the right tool or function at the right time. That means such conceptual information needs to be available right where it matters. Even if it means to give context with conceptual information inside a procedure topic, either in the introduction or even as a short sentence in the individual step.

Yes, such mixing of topic information goes against the rules of topic-based authoring, but it will actually help users: Offering such mixed information in context transforms the sheer information of how to do a task  (which is hard to remember) to knowledge of why and how to do a task (which is easier to remember.)

Context is everything

Ray said: “Context is everything” – which applies across the board:

  • User assistance needs to be available in the context of the user’s workflow. Embedding contextual information in layers, from GUI labels via tooltips to full-blown help topics, will support users accomplish their tasks faster and more easily without taking more of their attention than necessary.
  • Each piece of user assistance also needs to offer sufficient context to be meaningful and “learnable” for users: Only offering steps 1 through 5 in a procedure usually doesn’t offer enough context for users to actually learn how to use a product or a function, if we omit the “when” and the “why”.
  • User assistance also needs to offer enough context to allow users to navigate easily and with confidence through the product and the documentation. Specifically, we need to offer users an easy way back to where they’ve come from and a way back to the product and their task.

Offering successful user assistance isn’t a question of offering more at all costs, because more information isn’t necessarily better for the users. Instead, we need to stimulate cognitive demand, the will to know and learn, in the user by offering the right information at the right time.

Advertisements

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.

But do we create documentation with meaning?

Being meaningful is an essential, but elusive feature of good technical communications. Yet being meaningful in technical communications is just as essential as being correct and clear, concise or consistent: Understanding how and why communication is meaningful can help you to make your documentation more effective and to make your product more useful.

What is meaning?

Information theory suggests a hierarchy of information which proceeds from data at the bottom via information and knowledge to wisdom at the top. For example:

  • Data is the sheer fact that the Microsoft Office 2007 software has an “Office button” icon in the upper left corner.
  • The information is that this icon gives you access to functions such as opening, saving and printing a file helps you with generic functions.
  • The knowledge is that this functionality has replaced the File menu you’ve been used to. This adds meaning and supports your active experience.
  • The wisdom might be in the affirmation that nothing lasts. Or that Microsoft has flipped-flopped when they abolished something as sensible as the File menu – only to bring it back in Office 2010…

So meaning occurs at the knowledge stage in this hierarchy when you make sense of data and information, when you “connect the dots” into something that you can apply purposefully. Meaning gives answers to questions such as “So what?”, “What does this mean for me, in my situation?” and “Why should I care?”.

Why should technical communicators care?

Technical communicators should care about meaning, because we are in the business of creating meaning and transmitting it to users. We can provide all the data and information we want, if it’s not meaningful to customers, it’s wasted and dead. Any time documentation fails, it’s either because meaning has not been created or not been transmitted successfully. Documentation that merely informs the user “To print a file, click the Print button” does not support any active experience. It does not create any meaning, if it omits the context, such as the task the user may be engaged in, the prerequisites and the expected results of the user’s action.

– How can we ensure that our documentation is meaningful? Should we be thinking about meaning explicitly? Or is it enough to know our audience, use personas and create task-oriented documentation? Feel free to leave a comment.

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.

Top 3 reasons to do a language edit

There are several good reasons to do a language edit and most have to do with the overall quality and usability of your documentation. That’s the lesson I learned while editing our upcoming Release Notes for language.

The language edit is the unloved stepchild of the tech writing process: It is frequently last in line and gets less attention than the actual writing and the content review. Yet it really impacts the quality of the documentation, precisely because it occurs so close to publication. Here are three benefits of a language edit.

Correct, clear and consistent language

The most obvious benefit is to ensure that the language in the document is correct, clear and consistent. This is why you do it in the first place. And it is especially important if the documentation is written by several authors. Even if you have a really good and detailed style guide, you’re bound to get different ways to interpret it – to put it benevolently… 🙂

Ensuring clear language requires a language editor who is well-versed in the subject – but not so steeped in it as subject-matter experts (SMEs) who may review content who often have too much of an insider’s view and won’t spot potential misunderstandings. (Many SMEs are also uncomfortable with reviewing language, either because they lack the skills or because it distracts them from the review they should be doing.)

Ensuring consistent language requires an editor who reads across the complete document – instead of distributed authors and reviewers who work on a chapter each. Most chapters I encountered had their distinct style, but the differences between chapters couldn’t have been greater if they had been in entirely different documents. This seems to be a stylistic issue at first, but it spills over into the other two reasons for a language edit, so follow me on to the next item which is…

Consistent structure

Our standard operating procedure for writing Release Notes contains a standard structure which each entry should follow. Essentially, it looks like this:

  • Summary of enhanced or new feature
  • User benefit of feature
  • Prerequisites of feature
  • How to use feature
  • Results and next steps of feature

Depending on the scope of an enhancement, some of these structural elements per entry are optional. A new menu option may be self-explanatory enough, so we don’t need to point out the user benefit, and there are no special prerequisites. The whole entry may be but two sentences long.

However, it is a matter of judgment how many details and customer guidance we want to provide. For a team of distributed authors, this is almost impossible to agree upon before hand. A language editor can help to ensure consistent structure. This may require consulting with the author about missing structural elements, but if they’re quick to respond, it is well worth the effort.

Raising documentation standards and value

While you are talking with authors about missing elements, this is a good chance to offer feedback about recurring issues. I’ve noticed that some authors have their “favorite” mistakes. One has missed a guideline in the style guide and keeps repeating the same small mistake. Another may have a larger misunderstanding, whether it’s about topic types, the use of personas, etc.

The language editor not merely improves a document, but in the process also performs a thorough audit of current documentation practices. So she or he can help to ensure adherence to documentation standards and raise the value of the documentation you publish. A language edit is often the last chance to ensure your final document feels and works as it should and lives up to your corporate and documentation standards. Omit it at your own peril.

For more about editing, see my earlier post “Editing for tech writers“.

– Do you do language edits? What benefits do you get from them? Which shortcomings made you wish you had done one? Please leave a comment.

Find out how users use your documentation

Asking good questions of your users is essential to know how your customers use your documentation. This is part 2 after my post about using a survey to get to know your audience. The introductory paragraphs are identical to last week’s post, so feel free to skip ahead to the two paragraphs before the next heading.

A recent thread at Technical Writing World got me thinking about user surveys and revisiting two posts from 2010 where I wrote about obvious, but not so helpful questions and how to segment users and survey your documentation.

You can get all kinds of answers from your users, but depending on your questions, I find some answers more helpful than others. Jakob Nielsen’s position about usability makes a lot of sense to me:

Pay attention to what users do, not what they say. Self-reported claims are unreliable, as are user speculations about future behavior.

But if we cannot observe users, we have to rely on what they say – and try to ask them questions which yield useful answers. If you include an odd number of set answers in your survey, you can slice up the results (instead of having to deal with freewheeling answers), and users have a chance to select the option in the middle if they want to.

– Here are some questions that can help you to find out how successful your documentation is. Note that it doesn’t simply ask customers what they want. Instead, the questions can help you to determine which deliverables and which topic types (such as concepts and procedures) need improvement.

There are obviously other and better ways to determine user behavior, from usage analytics to user-generated content – but many technical writers don’t have the mandate or means to simply use them. These ideas are for them.

How do you use the documentation?

Do you use the documentation…

  • To set up & configure <our product>
  • To operate <our product>
  • To learn about the business
  • Not at all

When you need help, where do you normally seek information?

  • I look in <product> online help
  • I look in <product> user manuals
  • I ask a colleague
  • I call customer services
  • Other

How frequently do you use <our product> online help?

  • Daily
  • A few times a week
  • A few times a month
  • Once a month or less
  • Never

How frequently do you use <our product> user manuals?

  • Daily
  • A few times a week
  • A few times a month
  • Once a month or less
  • Never

How successful are you with the documentation?

Can you find the information you need in the documentation quickly and easily?

  • No, not at all.
  • More or less.
  • Yes, very much so.

Is the documentation that you find accurate and complete?

  • No, not at all. | More or less. | Yes, very much so.

Is the documentation clear and easy to understand?

  • No, not at all. | More or less. | Yes, very much so.

Does the documentation help you achieve your task?

  • No, not at all. | More or less. | Yes, very much so.

Does the documentation provide sufficient theoretical and business background?

  • No, not at all. | More or less. | Yes, very much so.

Are you satisfied overall with <our product>’s documentation?

  • No, not at all. | More or less. | Yes, very much so.

Your turn

Which questions do you use to find out whether your documentation hits the spot? Feel free to leave a comment.

A user survey helps you to know your audience

Asking good questions of your users is essential to know the audience of your documentation.

A recent thread at Technical Writing World got me thinking about user surveys and revisiting two posts from 2010 where I wrote about obvious, but not so helpful questions and how to segment users and survey your documentation.

You can get all kinds of answers from your users, but depending on your questions, I find some answers more helpful than others. Jakob Nielsen’s position about usability makes a lot of sense to me:

Pay attention to what users do, not what they say. Self-reported claims are unreliable, as are user speculations about future behavior.

But if we cannot observe users, we have to rely on what they say – and try to ask them questions which yield useful answers. If you include an odd number of set answers in your survey, you can slice up the results (instead of having to deal with freewheeling answers), and users have a chance to select the option in the middle if they want to.

Find out who your users are

If you write for different markets, audiences or countries, it’s important to distinguish user profiles and their answers. It will help you understand the answers in context of questions such as the following.

Which edition/version of <products> do you use most (please select only one)?

  • Users of “smaller” editions judge your product and company by the help they need from the documentation: If they get started quickly and find information easily, they will be more likely to recommend your product and upgrade to “bigger” editions.
  • Make sure you assign feedback correctly and don’t mistake criticism of older versions for feedback on your more recent efforts.

For how long have you worked in the industry? <or:> For how long have you worked with <products like ours>?

  • In B2B markets, novices might need more conceptual help than seasoned pros.
  • Experienced users can often offer more qualified feedback of your documentation in comparison to that of competitors.

For how long have you worked with <our product>?

  • Novice users rely more frequently on “Getting started” documentation
  • Experienced users can offer more reliable feedback on reference documentation.
  • Experienced users (especially if they are loud or many) require a comfortable change path when product usability changes. Remember the opposition to Microsoft Office 2007 ribbons by heavy users of previous versions.

How frequently do you use <our product>?

  • Infrequent users probably rely more on finding more basic information – and finding it again.
  • Frequent users may need more detailed information.

– What other questions should we ask about our users to ensure we put their answers into the right context? Please leave a comment.