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.
Filed under: conferences, technical communication, usability, users | Tagged: Ray Gallon, TCUK12 |
Kai's Tech Writing Blog 
“Yes, such mixing of topic information goes against the rules of topic-based authoring,”
Just a note for DITA fans or detractors – this is why DITA Task topics have a ‘context’ section, which can reuse from conceptual topics to provide clear contextual information before advancing into a task.
Good point, Noz, thanks!
Yes, we apply a DITA-derived information model which also includes (brief) context information in the beginning of task topics – and I’ve found that works very well, if only to let users decide whether they’ve come to the right place.
Kai, thanks for your review and summary, which catches many of the subtexts as well as main themes of my presentation.
Noz, the context section in a DITA task is useful but not sufficient. Sometimes you need to put conceptual information right in steps. For this I use stepresult or stepinfo. The reason to do this is based in cognitive learning theories.