Blog Archives

Adapting content for usability expectations at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.

Kirk St.Amant presented a session titled “Prototypes of Use: Adapting Content to the Usability Expectations of Different Contexts”.

Kirk has recently been working on “the auto manual phenomenon”. Think about opening up an auto manual and using the instructions on how to change a tire. Auto companies get plenty of complaints from customers about these particular instructions. At first the auto companies were puzzled, because user testing had showed the instructions were correct and easy to follow. After further investigation, it turned out that people couldn’t use the instructions, packaged as they were in a 450-page manual. Such a large book isn’t designed to be ready on a highway, in the dark, in the pouring rain. It doesn’t lie flat.

In other words, it’s a question of context. Where do readers actually use the doc? We need to focus on the delivery mechanism.

Consider how people use and process information. We associate a particular verbal representation with a physical object. Taking this further: The prototype that we use when we identify something may cause us to deliver the wrong product.

Kirk asked us to play a game, based on Physics or Maths textbooks. He asked us to describe such a book. The audience was unanimous about how such a book would look: Big, hardcover, blue or grey, with atoms drawn on the cover. We concluded that if we saw a thin pamphlet, we wouldn’t identify it as a Physics textbook. Similarly, we described the concept of a classroom.

When someone asks you to create a manual, you’re predisposed to create something that looks like a textbook, and probably something that fits into a classroom.

Instead, we should think: I need to create something that shares information on a particular setting.

We tend to use this formula when thinking of usability:

Content+audience = design

Instead, we should focus on:

Content+context[audience+setting] = design

Kirk now did a deep dive into defining the context of use, using a series of formulae and process maps to define the concepts and flows, illustrated by real-world examples.

Some cool terms:

  • a prototype jam – what you experience when you get stuck because some part of a familiar workflow is suddenly absent.
  • context mapping – a process for describing the objective, setting, and sequence of actions, for various contexts (objects, individuals, access points, exit options).

In response to a question about applying the results of a usability study: Kirk described how his team adapted the instructions for measuring blood pressure, based on the patients’ experiences using a blood pressure cuff and attempting to read a heavy manual simultaneously in order to report the results. Instead, the team substituted a voice-activated mechanism for reporting results.

The idea is to get engineers/designers to think about context at the start of the design process, so that content conforms to context.

Thanks Kirk for an educational, authoritative look at modelling usability and context.

What readers want at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.

Yoel Strimling presented a session titled “So You Think You Know What Your Readers Want?” He presented the results of a study that measured and compared how writers and readers define documentation quality, as well as how writers assume readers define it.

Yoel started by quipping that the most important word in the docs word starts with an F and ends with a ck: … Feedback.

The most important thing for good documentation is to know how well our docs work. For that, we ideally need direct, actionable feedback from readers. We have personas, user stories, use cases, journey maps – to make educated guesses. That’s not the same as actionable, direct feedback.

The definition of doc quality must:

  • Come from a reader’s point of view.
  • Be based on empirical, research-based feedback.
  • Use clear and unequivocal terminology.
  • Cover all possible aspects of quality.

Yoel found a study from 1998, based on 100s of interviews with information consumers, to find out what they wanted from their information. They came up with a framework for defining information qualities based on 4 categories: intrinsic, representational, contextual, and accessibility. Those categories were subdivided into 15 dimensions. Yoel talked us through an amusing illustration of these dimensions, to determine the relative quality of two pens. Part of this illustration involved losing his pen, which was tucked behind his ear!

Conclusion: To be of high quality, docs must be intrinsically good, clearly represented, contextually appropriate for the need, and accessible to the reader.

Yoel then created a survey, asking readers to rank the docs based on the 15 dimensions. He sent another survey to writers, asking them how they thought readers would rank the docs based on those same dimensions. The top results were very similar to each group:

  • Top qualities as judged by readers: Accurate, easy to understand, and relevant.
  • As judged by writers: Relevant, accurate, easy to understand.

But Yoel found 5 dimensions where writers significantly underestimate the value of the dimension to readers. In particular, writers underestimate the quality named “value to readers”. “Valuable” means “beneficial and providing advantages from its use”. Readers want us to give them docs that help them do their job better!

How do we help users to do their job better? Yoel asked the audience. These were some of the suggestions:

  • Make the tools and the docs easier to use.
  • Provide tips.
  • Give the users the simplest flow, and avoid bombarding them with options.
  • Pare down the information.
  • Base the docs on the readers’ goals.
  • Provide videos and graphics.
  • Give the wider context when relevant.

Client’s language at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.

Chrystal Mincey’s session was called “Know Your Client’s Language”.  Tech writers’ clients have different styles, and may prefer their writers to follow a particular style guide.

Define the client

Take a look at the client’s reporting structure, who your boss reports to, and going higher. The requirement that you’re tackling may come from higher up the chain. Look out also for conflicts of interest, and which division takes priority, especially if different divisions are competing for your time.

Client expectations

Find out the amount of time your client expects from you, and the times of day you need to work. Is flexitime an option? Find out the end goal of the client, and how your project is contributing to it. You’re there to make yourself look good as well as your client. Check the deadlines and milestones, and whether they’re negotiable.

Confirm your responsibilities, and whether there are other tech writers to cover while you’re out.

Client’s guidelines

Determine whether your client has a style guide, or whether they use a particular industry style guide. If there isn’t one, consider developing one. This may be time consuming, but gives you more control. Adhere to templates, if they exist.

Recipe for success

The end goal is for you to be successful, as well as for your client to be successful. Know what time your client arrives, learn their routine, and adjust your work practices to it. Is it OK to approach your client at 9am or should you wait until they’ve had their coffee?

Research in all ways possible.

Client is always right but may be open to change

See things from the client’s viewpoint. Learn their project as a whole, including how to work with the developers. Remember that everyone is working towards the same goal. If there are conflicts, ask the client to see things from your side, and remind them you’re working towards the same goal as they are.

Thanks Chrystal for a spotlight on how to work with a client.

Engineering content champions at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.

In her session, “Engineering Content Champions”, Becky Todd spoke about crowd-sourcing content. The session’s theme was that you can build excellent documentation by allowing contributions from engineers and product owners, but there are some rules to make it work.

Becky mentioned the dilemma of identifying ourselves as technical writers or technical editors. She works on developer-focused documentation, where you often find yourself writing less, and working more strategically to enable other people to create documentation.

There’s valuable, but hidden, content in places like email. This type of content solves many real problems, but it’s hard to find. As a result, she developed the idea of a content champion. These are people who curate content, even though that’s not their core role. They share knowledge, and get feedback on it too. Examples are support engineers, developers, product managers, and people in the community.

She started thinking about a crowd-sourcing mechanism for technical documentation. This involves a way of allowing occasional authors to provide content voluntarily.

Crowd-sourced content has a number of benefits. It helps you documents edge cases. People include knowledge from various areas of your organisation. And you can minimises bottlenecks and reduces pressure on a small tech writing team.

There are challenges too. Ownership becomes less clear, and people may decide not to fix a problem. Language may be poor, and content hard to understand. You may end up with quantity versus quality.

How to be successful with crowd-sourcing your content:

  • Communicate clear goals.
  • Document processes clearly.
  • Get support from all stakeholders.
  • Ensure that editorial review and oversight is in place.

The tool-kit you provide for crowd-sourced content is very important. Create a guide to contributing content, and ensure the workflow is simple and matched to your contributors. Provide style guides and best practices. Consider providing training for other areas of your organisation. Plan your content strategy, and how to receive feedback on the docs.

A good tip is to make sure documentation is regarded with respect inside your organisation. This shows respect for your customers who need to use the product. Becky showed us a page on the Django documentation site, which embodies this principle.

We walked through a case study of a crowd-sourced knowledge base. The project successfully replaced the repetition of question and answer that the support team had been subject to, with a base of 300+ articles on common questions and answers. The flow of information between support and engineering also improved the relationships within the organisations.

It’s important to reward or acknowledge the successes of people who contribute to the documentation. Use whatever mechanisms are available within your organisation, such as mentions in quarterly meetings, kudos, etc. This also raises the profile of documentation within the organisation.

Thank you Becky for a great session and engaging content!

Learning styles and the cancer experience at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.

This session was an interesting take on learning styles, by Debbie Kerr. She looked at the way information about a cancer diagnosis is presented, and how it could be done better based on the varying learning styles of the audience.

Debbie is a breast cancer patient and survivor, and advocate.

Goals for this session

The aim of this session was to learn about health literacy, the role that learning styles play in a cancer diagnosis, and how to improve the imparting of such information.

Approximately 10% of adults in the US have health literacy. In Canada, it’s 40%.

One possible solution to this issue is to use simpler language. Also, if reading is the problem, perhaps we could use something other than words.

Learning styles

People learn by doing (kinaesthetic), by listening (auditory), by seeing (visual), and by reading and writing (literate). But it’s more complicated. There are approximately 71 learning styles!

Different audiences have different styles. For example, your learning style is affected by you age, gender, level of education, existing knowledge, and emotional state. This latter is especially important in the medical world, relative to other types of technical documentation. Perhaps the recipient of the information is alone, or has time constraints, or receives the news at home/work.

The subject matter influences learning style. For example, you can read or watch all you like about sport, but you need to do it before you really learn. Medical information of essentially abstract, with lots of concepts and few consistent procedures. Most importantly: The learner is the recipient not the doer of the procedure.

So, the best you can do is to tie the information to something the reader already knows. For example, compare the size of a tumour to the size of a golf ball, rather than saying it’s n centimetres/inches in diameter.

Visual: Debbie showed us a very scrappy picture of hormone receptors that a doctor drew for her. Even though it was scrappy, it gave her a good idea of what was going on. She therefore created a better version of the diagram. Auditory: She also played the “Pump your Blood” video from YouTube, from the 1970s, as an example of auditory teaching.

Kinaesthetic: We saw a sample of some medical software called emmi. It showed the things that can happen to a knee joint. The learner would develop interactive software where they can select items to see the relevant instructional material.

The Know your Lemons campaign is interesting, because it very clearly shows the 12 symptoms of cancer, and because it gives people the option of looking at lemons rather than breasts. And it’s easier to download these images from the internet.

A learning style is a preferred but fluid method of learning that is influenced by various factors, some of which are listed above.

Thank you Debbie, for this engaging and informative look at learning styles.

%d bloggers like this: