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.

Topic-based authoring: The undiscovered country

NT Live Hamlet Many software companies, when they start out, provide user documentation as downloadable PDFs or as web pages. As they develop more products and versions, and as they expand into countries that use different English spellings, the amount of documents can grow until it becomes hard to keep all of these documents up to date.

It’s at this point that they tend to call a specialist technical writing company (such as Cherryleaf) to see if they can fix the problem for them. We find they’ve usually had a brief look at a Help Authoring tool, such as Flare or RoboHelp, and can see that it would solve a lot of their problems. However, they’re often not really sure how to use these tools in the best way.

Although topic-based authoring has been around for over twenty years, for many people it’s a completely new concept. It is, to quote from either Hamlet or Star Trek VI, an undiscovered country. Our meetings with them often end up focusing on the benefits of topic-based authoring.

Topic-based writing is an approach where you write a piece of text (or topics) that typically contains a paragraph or two about a single topic. These topics can be combined to create a page in a PDF document, and they can be organised in a sequence to create an online Help system ( See topic-based authoring page in Wikipedia). It’s a modular approach to creating content. The main advantage of this approach is the topics are often reusable; you can save time by reusing topics across different documents, and you can publish the same content to different media. For example, you could use a topic in training courseware, in a user guide and in marketing information.

As each topic is usually about a specific subject, and has an identifiable purpose, it can also help the writer write more clearly. If you need longer articles, you can build these up from the topics you’ve created.

It’s easy for professional Technical Authors to forget sometimes that many people have never come across this approach to writing before.

Why your Web content is like Doctor Who

Doctor Who logoDoctor Who is a popular British TV science fiction series that is celebrating its 50th anniversary later this year. So why is it like your Web content? Let us explain.

Regeneration is a part of life

The many faces of Doctor Who - WikipediaOne of the reasons why Doctor Who has managed to be popular for so long is due to the ability of the Doctor to regenerate: if he is old or mortally wounded, he can transform into a new physical form with a slightly different personality.

Similarly, your content may need to take on different forms over time. You may need to change the way it looks to suit different devices, or modify its personality (the tone of voice).

The basic fundamental story, or content, probably doesn’t not need to change greatly, as its purpose is likely to stay the same. However, it’s important to recognise and accept changes to the presentation format are now a fact of life for your Web content.

The Doctor’s companion

Clara Oswin OswaldIn most Doctor Who stories, the Doctor has a companion who travels with him and shares his adventures. The companion asks questions, often gets into trouble, helps the Doctor, and on occasions, rescues or challenges the Doctor.

The companion shows the importance of explanation – acting as the surrogate audience, asking the questions they may have, giving them important information and providing a persona they can relate to.

The readers of your Web content may also need a companion – someone who can assist them, enable them to have their questions answered. In the world of technical communication, we call this “User Assistance” or “online Help”.

Even the Doctor, one of the most expert of people needs an assistant. There are many times when he is overconfident, makes the wrong assumption, and is helped out of his predicament by his companion. This is also true for your expert users.

The sonic screwdriver

Whenever the Doctor wants to learn about a new world, a new creature or machine, he whips out his trusty sonic screwdriver. It gives him data that helps him understand how to solve his current problem. We need our own sonic screwdriver for our Web content – ways to measure its performance (i.e. if it’s meeting the users’ requirements), discover where the problems lie, and so on.

The Tardis of content

Tardis at BBC TV centre

The Tardis, as nearly everyone knows, is bigger on the inside than it is on the outside.

Unfortunately, only the Doctor knows where everything is located, and we generally only see a glimpse of what’s inside. We know there’s a swimming pool and a library, but often people get lost within the Tardis and end up where back they began.  There’s no official map of the Tardis, as far as we know, and it seems like there’s no logical structure to the corridors and rooms.

This is often the case with your web content. There’s lots of information, but it can be hard to find. If you know it’s there, you can search for it, but often you need a person to guide you to it.

Access to the Tardis is generally limited to those the Doctor invites in (or to those who are given a key). Many organisations take the same attitude to their online Help content: they hide it away from public view and, as a consequence, prospective customers.

The Whovians

Doctor Who fans Flickr image by Jason RiedyWhovians is the name given to fans of Doctor Who. Doctor Who has a huge and passionate following, which means they, in a way, “own” Doctor Who has much as the BBC and its writers.

Today, Doctor Who is a “Second Screen” experience: as people watch the TV show, they also converse on Twitter and Tumblr. The user generated content is an important reason why Doctor Who is so popular today. This can be true for your website as well: your users are part owners of your site and its content; their user generated content can be as important as the content you provide.

What have we missed?

Let us know if we’ve missed out any other links between Doctor Who and your Web content.

(Doctor Who fans Flickr image by Jason Riedy)

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

What can a Technical Author learn from a historical fighting manual?

The Wallace Collection recently held an exhibition on The Noble Art of the Sword, where visitors could see range of beautiful fencing manuals written during the Renaissance.

renaissance sword fighting manual

So could a Technical Author learn anything from the way historical fighting manuals were written? I have practiced aikido, a Japanese martial art, since 1992, so the thoughts below relate to the instruction manuals developed for aikido. In particular, the first aikido manual, Budu Renshu.

  • The writers. The instructions were not primarily written by the founder. Instead they were written by a student (or students), with the copy reviewed and approved by the Head of aikido. Perhaps the task of drawing the diagrams and writing the text was given to someone who had skills in drawing and writing instructions. The Head focused more on writing the chapters that explain the values and philosophy behind the art.
  • The purpose of the manuals. The purpose of the manuals was as a memory aid, not as a self-study guide. In the same way that you cannot learn how to ride a bike by reading a book, they were not designed as a replacement for practice time on the mat.
  • The audience. The instruction manuals were not written for beginners or for the general public. They were written for intermediate and advanced students.
  • The information design. The pages contained step-by-step images, with explanatory text below. Simple line drawings are used, to make the information more understandable. Some expertise is needed to understand the techniques, as 2D images were used to explain three dimensional movements. Sometimes, the diagrams change to a different perspective, which makes comprehension harder for the reader. Later aikido manuals added lines and arrows to indicate the direction of movement. One of these books, containing diagrams by professional illustrator Oscar Ratti, is still very popular today.

aikido in the dynamic sphere

  • The accuracy of the documents.The text-based instructions below the images in Budu Renshu have been useful in spotting errors in the diagrams. The manual was copied by students using tracing paper, and sometimes a mirror image was drawn by mistake.

It would be great to find out from someone involved in reviving the Renaissance sword fighting techniques if there are similar features in the manuals of Alferi, Rapisardi and others. Please let us know.

The wonderful, horrible life of User Generated Content

User Generated Content (UGC), that is user documentation written by users, is growing trend in the world of technical communication. However, although there are enormous benefits from UGC, we’ve found it can lead users to miss professionally written user documentation. The consequence of this can be that users search and navigate down blind allies in a search for useful and relevant information.

So is UGC creating a scotoma, or tunnel vision, in the mind of the users?

Let’s look at an example

This blog, by one software vendor, describes a solution for how organisation can host its own powerful content management system “in the cloud” for peanuts. It comes with disclaimers that this is not supported officially by the vendor, but there’s evidence it is possible. Via the comments at the end of the blog post, you’ll discover the original solution has been superseded, but the writer has helpfully provided a rough outline on the best way to do it today.

So the curious user is sent off on a quest to find the complete answer.

The first stop on this quest is the links in the article itself. Because the solution is not supported officially, in this example, the linked pages do not provide the full answer.

So what does the user do next? We found, in most cases, their second step will be to search on Google and see if the solution has been provided anywhere else. In this example, it will lead them to blog articles written by a variety of different people and organisations. This article, by Phil Paradis, for example, provides his solution to the problem.

We found the a key problem with the user generated content in the scenario above, it wasn’t clear whether the advice was still valid or not. A user could spend a great deal of time diving into the murky depths of Linux terminal commands, only to discover eventually that the hosting software part of the solution had been updated to be more user-friendly. What’s more, it now came with very clear user assistance.

Why are users going towards the unofficial documentation?

There are a number of possible reasons why users are more likely to be ending up looking at the unofficial rather than official documentation:

  • The user starts by reading a blog and expects the answer to also be in a blog. The reader has created a scotoma in their mind.
  • The search terms entered by the user into Google are more likely to lead them to unofficial content than official content.
  • Because the solution is not supported officially, the official documentation does not provide information on this topic.
  • The official user documentation is not ranked highly by Google.
  • The official user documentation has been poorly written, in comparison to the unofficial content.

What is the solution?

A lot of software solutions are based on integrating a number of applications and services together, and it’s not uncommon for people to be looking for the type of answer outlined in the example above.

As there are a number of reasons why the problem may occur, so there are a number of possible solutions:

  • The official user documentation needs to be findable via Google. If users begin their quest by searching, then they are likely to continue to use that approach.
  • Present professional user documentation and user generated content in the same system. If they begin by following links, then they likely to continue using that approach. If we can guide users to professional user documentation, with all the version control and provenance information it usually contains, at the right time, then we may be able to combine the best of both types of user documentation.
  • Engage with the bloggers via the comments to provide links back to the official documentation.
  • Consider the search terms users might enter and provide information that will appear high in the rankings. This may involve creating pages on topics that are not supported officially and contain a number of caveats.

We welcome your thoughts and comments.