The big questions in technical communication

David Farbey wrote a semi-existentialist post on the challenges for technical communicators yesterday. I’d like to look at the issue in a different way, by looking at the big questions in technical communication today. The answers to these questions (which may be decided by people outside of the profession) are likely to affect the future direction for technical communicators.

Continue reading

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

Our next Advanced Technical Writing Techniques course – 24th April 2014

After a short break, our Advanced Technical Writing Techniques training course has returned. We’ve scheduled a public course for Thursday 24th April 2014, in South Kensington, central London.

Past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger and Visa International. One delegate commented:

“The way in which customers consume our content is changing, as are the different expectations customers have regarding user assistance and support. Your course provided further insight and ideas regarding how to review and adapt to ensure content is relevant and appealing to our customers.”

This course is ideal for Technical Authors and those developing assistance for users of software.

Discover the advanced new writing styles emerging in technical communication. Don’t get left behind. You can book a place via the webpage Trends in Technical Communication Workshop – Advanced Technical Writing Techniques.

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.

What would a Technical Author ask from Santa?

Santa Claus - WikipediaSaint Nicholas’s day has passed, which means Christmas is getting close. So what would a Technical Author ask from Santa Claus?

One thing we could request is the ability to embed one Google document inside another. That would mean that Google Docs could support some basic content reuse.

Another would be to request Madcap Flare’s DITA support to be extended, so that you could create edit native DITA files.

We could ask him to provide a standard technology format for providing Help for mobile applications.

We could also ask him for a way to use Siri and Google Voice Search to interact with our user guides.

So what would you ask Santa to bring? Please share your thoughts and ideas below.

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