Author Archives: Sarah Maddox

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.

Journey mapping 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.

Michelle Gardner‘s session was titled, “Walk in Your Customer’s Shoes: Learn the Art of Journey Mapping”. She showed us how to create a journey map, which helps us determine the needs and problems of our customers.

A journey map is a story told from a user’s perspective about all the steps they take to get something done.

What we need to do:

  • Know the users and their goals.
  • Write about the action they need to take
  • Know what the user wants at each stage
  • Satisfy the user’s need.
  • Remove obstacles from their path.

The user’s perspective

Michelle took us through a group of fictional characters who are visiting a coffee shop, to see if they’re represented by the same persona. The aim was to delve into particular points of view, when developing a persona. Make sure you have facts rather than assumptions. If possible, observe users using your product. Otherwise, talk to people who know the customers.

Each journey map must have one persona, and each persona must have a journey map told from their point of view.

The actions a user takes

The user goes through multiple steps in the task they need to complete. For example, at a coffee shop the steps may be: view their choices (e.g. via a menu), place the order, pay, etc. Michelle used the example of a menu to point out that we should not be technology-specific at this point – the user may see their options on something other than a menu.

Considerations for each action: For each stage, we should know the actions the user takes, their thoughts and feelings, the timeframe, the user’s expectations or goals for that stage/timeframe, the channel/medium/location, your assumptions, and moments of truth. The last item means those interactions with your product where the user perceives quality or lack of quality.

If possible, you should also know the other characters involved, whether the step is necessary (maybe it’s only required for some personas), where the user came from and where they’re going next.

The pattern of a user journey

As a [persona] I want to [intent] so that [goal or need].

During the session, we did an interactive exercise at this point, where we mapped the user journey of a sample persona: Lorelei Gilmore. We worked on a matrix, with the actions listed across the top, and the list of considerations (thoughts and feelings, timeframe, etc) listed vertically. We filled in the matrix with values that we thought might apply to Lorelei as she went through the actions required to order a coffee.

This was an interesting exercise, even though the use case was trivial (ordering coffee). It gave us insight into how many choices and options there are in a simple action. We also explored ways of categorising the different aspects of the use case.

Question from the floor: How long does the process of creating a journey map take and how many people would you expect to be involved? Answer: The first journey map would take at least a week. Involve the entire product team.

You need to do your journey mapping at the very beginning of your development process – in the design stage.

Observation from the floor: This seems more of a process for the product management, rather than a tech writer.

Question from the floor: How do you reconcile different personas with the same goal? Answer: Do a journey map for each persona, and analyse the stages where they’re the same or different.

Question from the floor: Is there ever a point in a journey map where you realise this journey map is not relevant? Answer: This would indicate that you’ve created a persona that isn’t relevant. You need to know your customers really well, and base your persona designs on the customers that matter.

How to apply a journey map to your product and docs

Michelle suggested some tools for journey mapping, such as Excel, PowerPoint, or Post-it notes on a wall. There are also professional tools available.

Design the product based on what you’ve learned. For example, add/remove features, and provide alternative options in the user interface.

In the documentation: Provide targeted content for each persona. Organise the content based on the journey. You can do journey mapping entirely for the docs, and then suggest to the product team that they apply it to the product too.

Thanks Michelle, this was a fun and enlightening session.

%d bloggers like this: