The conversation confusion in technical communication

Flickr CC image by Search Engine PeopleWe noticed last week a few tweets in our Twitter stream about how technical documentation and user assistance will be turning into a conversation.

A dictionary definition of conversation is:

1. The spoken exchange of thoughts, opinions, and feelings; talk.
2. An informal discussion.

 

Informal, verbal, interactive, spontaneous communication is quite different from pretty much all forms of User Assistance you’ll see today, so what do technical communicators mean by “conversation”?

Continue reading

Book review: Every Page is Page One

Every Page is Page One book coverThere’s a joke in education along the lines that students are taught the notes their teachers wrote down at university 20 years earlier…without going through the heads of either.

I mention this because there have been a number of technical communicators who have started to question the technical writing best practices that have been taught to student Technical Authors for the past 30+ years. At Cherryleaf, we show on our advanced technical writing techniques course how some of the largest websites have been breaking the generally accepted rules for writing User Assistance – companies that test and test again to see what works best for their users. Ray Gallon of CultureCom has been developing his cognitive approach to User Assistance, and Mark Baker has been developing and promoting the idea of “Every Page is Page One” (EPPO) Help topics.

Mark has published his ideas in a new book called “Every Page is Page One“. I was asked to review an early draft of the book, and, over Christmas, I was sent a copy of the published version.

In a nutshell, Mark’s argument is that, with Web-based content, you don’t know the context in which people are reading a Help page. You cannot assume that they have read any other pages prior to reading this topic. Therefore, you need to treat every page as Page One, the starting point, and include more introductory, contextual information in your topics. He argues that most Technical Authors have misunderstood minimalism, and the EPPO approach is actually more consistent with how John Carroll (the creator of minimalism) recommended User Assistance should be written.

The book provides recommendations on the level of detail you should include on a page before you need to create a new topic, and when and where to create links to other pages. He also compares EPPO to Information Mapping and DITA, and outlines how EPPO can complement these standards.

Reading the early PDF draft with a reviewer’s eye was struggle at times, but reading the final version in printed book format was an easy and enjoyable exercise. Perhaps reading some sections for a second time helped, as well.

We agree with a great deal of Mark’s ideas. We agree with the general idea of self-contained topics that provide the context for a task. We agree with the need for mini-Tables of Contents and a bottom-up approach to writing. We agree that tasks should include some contextual information. We agree online content can be atomised too much. We also liked his analysis of why screencasts are so popular, and the secrets to their success.

We have a few minor issues. Mark cautions against duplicating content on more than one Web page, because it’s bad for Search Engine Optimisation. We believe you should write efficiently in a way that’s best for the user, and that it’s up to the Search Engines to improve their algorithms so they can differentiate between “good” duplication and “bad” duplication. Google should be adapting and learning from the way good content is written, not us having to create sub-optimal content in order to satisfy Google.

It’s a book for people involved today in writing online User Assistance. Although the book is very clear and well structured, you probably need to have some experience of creating User Assistance to fully understand everything that’s covered in the book. It’s an important contribution to the discussion over whether technical communicators have focused too much on production efficiencies to the detriment of creating content that’s actually of value to their users. It’s worth getting a copy of this book.

Every Sherlock Holmes needs his Watson (or Molly)

Sherlock wallpaper image from The Consulting Detective blog

Series 3 of Sherlock has just started on BBC One in the UK. As nearly everyone knows, Sherlock Holmes is a genius consulting detective. Yet, as the saying goes, every Sherlock Holmes needs his Watson (or, in the first episode of this series, needs his Molly).

Sherlock Holmes is only a part of a pair, and his partner (Dr John Watson or Dr Molly Hooper) is as an important factor in his success. Watson observes and translates Holmes’s genius so that others can understand and follow. He asks the questions on our behalf. He also has skills that Holmes lacks – technical knowledge (about medicine) and social skills. Watson is nobody’s fool.

In another situation (such as working in a software company), we might call Dr Watson a technical communicator, don’t you think?

Happy 2014 – we wish you (and ourselves) a productive and communicative new year.

Changing times in technical communication 3 – The long form Help topic

New York Time snow fall article imageOne of the most recent developments in web page design has been the introduction of “long form” web pages. Will we also see the long form approach used in Help, or perhaps start to influence the way some Help pages are designed?

Continue reading

Changing times in technical communication 2 – Workflow

Science Museum/Science & Society Picture LibraryWe’ve been on the road in recent days and weeks, visiting different documentation teams, and we’ve found there are distinct signs of change. In this post, I’ll look at how we’re starting to see the workflow for creating User Assistance beginning to change.

We found many documentation teams overstretched and starting to be asked how they could create content for new products that were coming along. Some organisations have decided they can only deal with this extra workload if they rethink the workflow for how content is created.

Continue reading

Are your user manuals (and any other content) ready for Google Glass?

Google_Glass_detail from WikipediaGoogle Glass, a wearable computer with a screen above the right eye, goes on sale in 2014. Glass is almost certainly going to be used to support maintenance and repair calls, providing technicians (and other types of user) with the ability to access manuals and discuss situations with remote colleagues.

So are your user manuals, and the other content users might need to access, compatible with Google Glass?

Continue reading

Are page layout online documents evil?

Editor’s Note: This post has been written by Dr. Tony Self of HyperWrite. Tony will delivering DITA training during October at Cherryleaf’s training centre in London. 

Evil by Design book O'Reilly Press

Evil by Design book. O’Reilly Press

UX Magazine recently published an article called How Deceptive Is Your Persuasive Design, by Chris Nodder. The article hasn’t got a lot to do with UX (user experience) design, although Nodder’s book, Evil by Design, certainly does.

The article highlights ways in which eCommerce Web sites deceive customers in order to entice them to buy a product or service, and makes us think about where the dividing line sits between persuasion and deception. Nodder included a little diagram to help illustrate that”evil” design can be identified as design that benefits the designer without any corresponding benefit to the customer. He categorises ”commercial” as being a design that benefits both designer and customer, leaving ”charitable” to describe designs where the benefit is to society as a whole rather than to designer or customer.

This thought-provoking article (and diagram) got me thinking about whether the adherence to page layout design in technical communication for online transmission of information might fit this category of ”evil”.

Continue reading