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 GallonTom 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

The future of technical documentation is more about psychology than technology

In the quest to offer better forms of user assistance, most experts in the technical communications profession propose technological solutions: using XML, intelligent and adaptive content etc. to present essentially the same type of guidance as has been provided for the past 20 years.

We believe there has been a change in the relationship between people and technology, and there needs to be a corresponding change in the relationship between people and the user documentation.

In the past, a lot of technology was unfamiliar, idiosyncratic, expensive and complex; users often became anxious when they used a product. As technology has become part of everyone’s daily lives (particularly Web and mobile applications), people’s relationship with a great deal of technology has changed.

As a consequence, for some types of products and for some types of documents, the traditional approach for technical writing is no longer appropriate.

This means Technical Authors need a better understanding of this relationship – the psychology of users – and understand how they can relate and communicate to users in context.

We are not suggesting that the traditional approach to technical writing should go away completely. We’re also not arguing against technology such as XML and DITA – these are vehicles for delivering content. We’ll still be writing user documentation for scientific equipment and financial systems in the traditional way, as these types of products fit the traditional model. However, even the documentation for these types of products can benefit from the inclusion of some psychological techniques.

Web sites such as voiceandtone.com indicate some of the changes that we are likely to see in technical documentation, but we disagree with some of the approaches suggested on this site for some types of documents, and we feel this site only scratches the surface.

There is evidence from randomised control trials that these new approaches work, although we recommend you carry out your own testing to double check it works for your users.

So having come to be belief that Technical Authors need to incorporate some new techniques into their documentation, what should happen next? One approach is to engage Cherryleaf to provide advice or write documents. In addition, you’re able to discover these techniques through our new advanced technical writing training course. However, the starting point is to recognize the change in the relationship between users and many products, and to recognize the need to change the approach to technical writing so that it’s appropriate to the situation.

The question is, do you agree?