Blog Archives

APIs, maps and apps at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. This post is a summary of the session I presented.

My session was titled “A tech writer, a map, and an app”. I told the story of my odyssey into app development, and used my own journey as a way of teaching attendees about apps, APIs, code, maps, open source, and hackathons.

The slides are available on SlideShare: A tech writer, a map, and an app.

We explored some technical details:

  • The nuts and bolts of a web-based application like Tech Comm on a Map: where it’s hosted, where the data is stored, the JavaScript code and the APIs that create the map and the app’s functionality.
  • How the app’s data is crowd sourced.
  • What open sourcing your code means, and why you may want to do it.
  • The difference between a web-based application and a mobile app. Tech Comm on a Map is available as a native Android app as well as a webapp.
  • The information sources that I used when developing the app.

And we examined how such a project can help develop your soft skills:

  • My engineering colleagues helped me kick off the development of the app, and made ongoing suggestions for refinement. The resulting interactions increased mutual understanding and respect.
  • Fellow technical writers all over the world help compile the data. A project like this is a good way of connecting with your peers.
  • Developing an app can help you better understand your subject and your audience of software engineers and other specialists.
  • Such a project gives you confidence in your own abilities, even if you’re just skimming the surface of code complexity.

There’s more about the app on this page: about Tech Comm on a Map.

Thanks to everyone who attended the session!

Advertisements

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!

%d bloggers like this: