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.

Leah Guren’s Fish Tale at TCUK12

After opening remarks by conference organizer David Farbey, Leah Guren‘s keynote relevant and entertaining keynote address presented several lessons from the animal world:  A Fish Tale: Improve your Career by Watching Fish!

  1. Take a leap of faith – like salmon. It simply takes some guts and a little bit of faith that tech comm is here to stay, else you won’t be able to make a long-term plan and get behind it.
  2. Stay in school for better chances of survival – once you took that leap, keep honing your skills, keep developing. There are lots of ways and many don’t require the same amount of time and money as going to a conference, whether it’s e-zines, forums, user groups or webinars (some excellent ones are actually free!) Be sure to make your professional development part of your regular work schedule.
  3. Invest in better PR – the difference between a carp and coi is mainly the prize tag – which is thanks to better PR for the coi. Communicate your value that you bring to the company and to its customers. We know how much words matter, so we can do better than calling ourselves technical writers. “Information architects”, “content strategists”, even “technical comunicators” can make more money.
  4. Find the right stress – (sorry, I forgot how this related to fish… 😉 ) Tackle your fears, get a new challenge and pick the kind of stress where you’re still in control, feel stimulated and can grow.
  5. Active swim in a larger pond – because like a carp you will grow (professionally) in relation to the size of your “pond”. Find opportunities for growth how you can be the expert in your environment.

I’m sure I forgot a couple of Leah’s lessons. Nevertheless, I want to add an additional lesson that I’ve found important: Know the secret of the birds. That means know how your enemies tick, so they don’t eat you. Or if they’re not threatening: Seek heroes outside of your immediate field. Sure, you won’t be able to fly like a bird, but you can still find birds inspiring.

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.

3 motivators you share with your tech comm readers

What motivates you to work most likely motivates most of your users in their jobs, too! You still need to know your audience, their tasks and background, but the good news is that you have some basic motivators in common. And these can help you understand what makes you happy at work – and what makes your users successful in their work with your documentation.

The three motivators

I take my cue from Walter Chen’s post “The science behind what motivates us to get up for work every day“. I want to focus on three motivators Chen quotes from Daniel Pink:

The 3 real reasons that motivate us to work hard every day

Pink explains … that there are in fact just 3 very simple things that drive nearly each and everyone of us to work hard:

  1. Autonomy: Our desire to direct our own lives. In short: “You probably want to do something interesting, let me get out of your way!”
  2. Mastery: Our urge to get better at stuff.
  3. Purpose: The feeling and intention that we can make a difference in the world.

The motivators for technical communicators

Pink’s model resonated with me, and I think this is exactly what motivates me to do good tech comm work and try to get better at it:

  • Autonomy for me means to find something good in the benign neglect that often meets my efforts. Of course, I have specific products, deliverables and deadlines to comply with, but our documentation team is lucky enough to be able to define its own standards and processes as long as they’re feasible.
  • Mastery is the challenge to write better documentation. When I revisit obsolete documentation that I’ve written some years ago, it makes me smile: Seeing where I’m coming from and what I wouldn’t do anymore gives me a sense of progress. I’m still using task orientation and topic-based authoring – but I wouldn’t awkwardly mix concept and task in the same topic like this anymore.
  • Purpose for me is my reward that my readers can be more successful or simply faster in their work if and because I’ve given them the right information at the right time.

So in a very personal, non-scientific way, I could validate these three motivators.

The motivators for documentation users

I don’t think I’m all that different from my readers in this regard. I believe they get motivated by the same things – they’re just in a different job.

So I try to keep in mind the motivators when I structure and write my documentation:

  • Autonomy is tricky, of course. Someone looking up documentation has just given up the autonomy of a self-directed life and needs instruction or information. But I still try to acknowledge this and follow Pink’s advice above: “You (dear user) probably want to do something interesting (or important), let me (give you what you seek and) get out of your way!”
  • Mastery is where tech comm can really excel. By presenting essential information concisely and clearly we can make it easy for our users to master their tasks and their use of our product. For this mastery, it doesn’t matter whether users learn from the documentation and internalize a skill or whether they simply know where they can look up again quickly what they don’t need to remember.
  • Purpose is frequently neglected, I think. Often documentation focuses on the how, and forgets the why. But there is no sense of purpose without a why. Granted, not every topic can address the big questions of life and the universe. But as long as there is an elegant and possibly noble reason for why our product and its tasks are this particular way, it’s worth sharing it. It will give our customers an extra motivation – and make them more loyal users.

Is this what motivates you? Does it work for your readers or do they have other motivations? Please leave a comment.

How meaning works in technical communication

Considering how meaning works in communication in general, it should be easy in technical communication in particular, because several parameters are fixed.

Last week, I asked whether we actually create meaning in our documentation. Today, I take a closer look at semiotics to find out how meaning is created in communication – and specifically in techcomm.

How meaning gets transmitted in communication

Semiotics is a theory that explains communication as the production of meaning between people who exchange messages in cultural contexts. Semiotics aims to explain how communication is meaningful for a reader. (For much more on semiotics, check out Daniel Chandler’s good introduction Semiotics for Beginners.)

Note that the reader is not just a passive recipient of the message, but the active participant who constructs the meaning of a message. That is not to say that the meaning is whatever the reader wants. Rather, the meaning arises from how readers interpret the signs according to shared common conventions. For example, a user will – more or less – assume that a user manual contains photos or schematic images that represent the layout of the product, not an ideological statement, and try to create meaning accordingly.

Semiotics can get quite complex, due to all the moving parts:

  • Signs, such as words or even images, can lend themselves to creating different meanings at different times or for different groups of readers. (Think of ideologically, religiously or politically charged words or images.)
  • Semiotic “codes” can make you feel a member of the group, like your own regional dialect, or they can exclude you, like academic jargon. Whether you feel included or excluded influences your understanding of the message and the meaning you take from it.

However, technical communication suffers less from these shifts and ambiguities, because a lot of our signs and codes are restricted and well-defined. Or are they?

Why meaning seems easier in tech comm

Much technical communication can avoid some of the semiotic pitfalls because it addresses a limited, rather homogenous audience. We can assume a general willingness to learn the applied “code” of descriptions and instructions such as a user manual contains it. A manual can presuppose a certain vocabulary or define it in its glossary. The context is confined to the intended tasks of the products, and the expected outcomes of the tasks should be clear.

With all these major restrictions on communications in place, the user’s path is confined to a tunnel, and all that is left for the manual to do is to put in some lights and a railing to safely guide the readers through.

– If it was that easy, we wouldn’t find meaning in technical communications so elusive – and we wouldn’t despair to get users to follow the documentation. So our daily experience tells us that it doesn’t quite work that way.

– I’ll explore this problem at my presentation “Addicted to Meaning: How Good Technical Communication is Like Bad Magic Tricks” at tekom/tcworld in Wiesbaden on Tue 23 Oct at 1:45 pm. In the meantime, feel free to leave comments or questions below.

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 TCUK12 is a unique conference

TCUK is one of my favorite tech comm conferences thanks to its unique blend of varied, yet relevant progamming and a diverse crowd in a small, personable conference.

Logo of the TCUK conferenceTCUK in Newcastle from 2 to 4 October will be the third time I attend the conference, and if anything I’m looking forward to it even more than in previous years. Here are 3 reasons for my anticipation.

1. Interdisciplinary sessions

All tech comm conferences, including TCUK, manage to put on a diverse mix of interesting and applicable sessions. TCUK excels in reaching out into other disciplines.

In previous years, presentations covered fields such as statistics, public speaking, user experience design, and cognitive science. Not only were those sessions engaging, they also took care to show how they’re relevant and applicable to technical communications. (Full disclosure: I was co-presenter at one of those sessions.)

2. Diverse crowd

While larger conferences like the STC Summit and tekom/tcworld can be a bit overwhelming and anonymous, I find TCUK has a very good size: Large enough to draw a diverse crowd of interesting people, yet small enough that I never felt I was lost and still looking at strangers’ faces on the third day.

3. Personable vibe

The organizers from ISTC manage to create a professional, communal vibe that all but eliminates the differences between speakers, seasoned attendees and newbies. As far as I know, the organizers want speakers to attend the full conference, if at all possible, to encourage networking.

If you know other reasons that make TCUK unique or if you’re wondering just how good it is, feel free to leave a comment.

Welcome to summer reruns, episode 2

My blog and I are taking it a little easier for a couple of weeks.

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 walk on the beach… 🙂

As I’m gearing up for the new season, here are some reruns from the 10 most popular posts.

Improve documentation with quality metrics

… in which I argue that quality metrics for technical communication are difficult, but necessary and effective (complete with a picture of the seal of quality!).

How and why to estimate writing efforts

… in which I explain why, what and how to estimate efforts and deadlines in technical communications.

Top 10 reasons for tech writers and trainers to collaborate

… in which I give eight reasons why technical communicators can and should collaborate with trainers – and two why they cannot afford not to do it.

Welcome to summer reruns, episode 1

My blog and I are taking it a little easier for a couple of weeks.

I really enjoy writing posts, hearing from you and keeping in touch with other tech comm’ers from far and near. And I thank every one who’s stopped by to chime in or just to read! I keep learning from your comments, and I appreciate your support! It’s been a warm summer’s breeze… 🙂

As I’m gearing up for the new season, here are some reruns from the 10 most popular posts on my blog.

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

… in which I draw parallels between a help system, a department store and a library to illustrate how customers want to navigate each one.

Top 3 success factors in online help systems

… in which I apply some of Cameron Chapman’s “10 Usability Tips Based on Research Studies” to online documentation and come up with factors that can make or break help systems.

Top 4 benefits of writing a tech comm blog

… in which I celebrated my blog’s first anniversary, reminiscing about the various ways it’s been good to me – and continues to be!  🙂