Common sense isn’t always common

Here’s some examples from Munich of what might seem to obvious and common sense to the one audience, but not to others.

Traffic lights that have four lights, with the symbols , O, I and K:

Munich traffic lights

Pedestrian crossing lights that have two people instead of one:

Munich traffic lights

The second set of lights is still comprehendible (hold the hand of the person next to you, whilst you’re waiting to cross the road ūüėČ ), but the first set didn’t make sense to even the (non-Bavarian) German members of our party.

Issues for developers moving from on-premises software to Software as a Service.

On Monday, I spoke at the Visma Developer Days conference in Riga, Latvia, about some issues software companies have to address when migrating from developing on-premises software to Software as a Service.

One of the of the biggest changes is that the revenues are spread over the lifetime of customer – they pay on a monthly basis rather than an initial up-front payment. It becomes vital customers don’t give up on using the software after only a short while, because you won’t have earnt much income from that customer. If the software is difficult to use, and if users cannot find the answers to questions when they need them, there’s a good chance they will stop using the software, and stop paying their subscription fees.

We’re seeing a number of software companies changing their approach to providing user assistance (user documentation). More companies are thinking about it at the start of the project, so they can do a better job of delivering user documentation than they’ve done for on-premises software. They’re seeing documentation as part of the customer journey, and part of the design process.

This is welcome news, although it requires development teams to combine product design with information design. I wonder if there’ll be similar trends emerging at the next conference I’ll be attending – MadWorld 2014.

Design-led technical documentation

Peter J. Bogaards posted a link on Twitter yesterday to an article and a press release on how IBM is adopting a design-led approach to software design.

‚ÄúIBM Design Thinking is a broad, ambitious new approach to re-imagining how we design our products and solutions … Quite simply, our goal — on a scale unmatched in the industry — is to modernize enterprise software for today’s user who demands great design everywhere, at home and at work.” (Phil Gilbert, general manager, IBM Design)

I understand the IBM Design Thinking approach will affect everything it does: product development, processes, innovation, and, interestingly, the technical documentation/user assistance associated with products. Both design and traditional technical communication share the same goals Рto deliver something that is very usable, robust and aesthetically pleasing Рso it makes sense to have the two teams aligned closely.

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.

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

Where is User Assistance going? A summary of the bloggers’ thoughts

moral compass Flickr image by PSDThere’s been quite a few blog posts recently by a variety of bloggers and companies about the current state of User Assistance (such as online Help) and possible ways it could be improved. We thought it might be useful to provide a summary of all the different ideas floating around.

This summary primarily looks at the ideas proposed by¬†Mark Baker, Ray Gallon,¬†Tom Johnson, ourselves at Cherryleaf, Sarah O’Keefe/Scriptorium¬†and¬†Tony Self.
Continue reading

You can now create a free iPad magazine for your online Help, training and support content

Flipboard magazineFlipboard is a popular app for the iPad and Android devices that presents information in a magazine layout.

Users can subscribe to different topics, with the content pulled in from the links tweeted by their friends on Facebook and Twitter. They can also view Web sites and blogs (if they contain a RSS feed) as an online magazine.

Flipboard has just released version 2 of its application, which enables users to create their own magazines by clipping content from a variety of different Web sites.

In other words, brands can now curate their own selections and publish these¬†in a consistent and elegant looking format. Flipboard¬†will create a cover for your magazine with “pull out” headlines, and it will notify you¬†if other people have commented on the items you have included in your magazine.

According to Flipboard, since its launch, their users have been creating one magazine per second.

For Technical Authors, this means you could easily deliver online Help, training, user generated and support content in an attractive looking format.

According to The Daily Telegraph:

This latest move marks an even bigger, more significant step, taking the principle of a personalised and interactive internet, and bringing that to mainstream content delivery…This move confirms that the nature of content delivery is changing. It‚Äôs no longer about capturing crowds of many, but the audience of one. This audience of one doesn‚Äôt care about the usual magazine and newspaper release schedules, or about trawling through multiple sites to find the articles of most interest; it wants to read its favourite piece of content when it wants, and how it wants and values the curation of like-minded tastemakers, who provide a means to discover new content and cut through the clutter.

You can already view the Cherryleaf Blog as a Flipboard magazine (in Flipboard, just search on Cherryleaf or http://www.cherryleaf.com/blog/feed/), and you’ll also find a test magazine we’ve created called “The MadCap Writer”.

Let us know what you think of the potential for using Flipboard in User Assistance.

See also: Cherryleaf content strategy services

New design models for providing end user Help

Ray Gallon has recently completed a series of webinars looking at new models for providing end user Help (A Cognitive Design for User Assistance).

In the third webinar, Ray looked at how people learn today and he suggested a new approach for the future. He used The¬†Common European Framework of Reference for Language‘s description of people’s levels of competences to outline the different ways organisations help people to learn.
Continue reading