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.

Lars-Po Faydöl: The man you see in every Ikea installation guide

ikea man

Lars-Po Faydöl is a person you’ve probably seen hundreds of time, yet it’s unlikely any of you know who he is. Lars-Po works for Ikea, and the reason why you’re likely to have seen his face is that he appears in pretty much every installation guide that Ikea supplies.

You might not recognise him from his photograph, as he is represented in the guides as a two dimensional, line-drawn character, such as this:

ikea man

I bumped into him recently at a Solo Pal Friday networking event, and I asked how he ended up becoming one of the few “instruction life models” in the world. He said:

Continue reading

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.

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

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

Getting information from Subject Matter Experts

Flickr photo an interview by illustirInterviews with Subject Matter Experts (SMEs) are some of the most useful sources for Technical Authors when they are gathering information about a product or procedure. This often involves asking a developer or departmental manager a series of questions focused on the types of questions end users are likely to ask.

Interviewing is one of those dark arts that Technical Authors pick up over time – techniques for getting SMEs to find the time to speak to you and review your drafts, ways to avoid conversations meandering away from what the user will want to know, tools for capturing the interview, and so on.

So what tools should you use?

Coming armed with biscuits (cookies in the USA) is probably the most effective tool! After that, the most useful tool to have is a voice recording device. If you have a smartphone, in effect, you have a digital voice recorder. There are many voice recording apps for both iOS and Android, but the one we like is Recordium.

Recordium

In addition to recording audio, Recordium also enables you annotate the voice recording. You can highlight and tag certain parts of audio recordings (for example: to indicate a new topic or to mark sections that relate to definitions of terms etc), and add attachments to those sections as well. You can use it, in effect, as an audio-orientated note clipping application, similar to Evernote.

Recordium also enables you to vary the playback speed. We’ve found this useful when SMEs are using specialist terminology – you can slow down the recording to check what it was they actually said. Listening at a faster speed is also a useful way of reviewing a recording quickly.

Technical Authors still need to transcribe sections of the interview, so it becomes text. Unfortunately, Text-to-Speech applications still have some way to go. Dragon Dictation is available for Apple devices, and ListNote offers similar functionality for Android. However, even if you are just a two fingered typist, you’re probably better off transcribing the audio yourself.

Are there any other apps you’d recommend? Let us know.

Assessing the potential savings from single sourcing

One of the main benefits from single sourcing is the ability to reuse existing content. Different departments can avoid duplicating work, which means they can save time and money.

Unfortunately, it can be difficult to quantify these savings before you move to an authoring or content management system that enables you to single source. Analysing all the existing documents in a business can be overwhelming, which means often organisations only quantify the savings after the single sourcing content management system has been implemented.

There are a few software applications that can help you analyse your existing content and determine how much duplication exists. You get a sense of how much time and effort was wasted in the past, which is a pretty good indication of how much waste you’d avoid in the future.

Continue reading

Better content through analytics

At this week’s London Agile Content Meetup, Lana Gibson of the Government Digital Service (GDS) outlined how they use Google Analytics extensively to check and improve the user journey on the GOV.UK website. She said GDS treats this analytical data as the voice of their users – with GDS needing to interpret it and provide what we, as UK citizens, need.

Lana said they need to see what content is getting the most traffic, so that they can ensure that the most popular content is of top quality, and is prioritised within the site.

One of the key actions analytics have enabled them to do is improve the connections between different but related needs that were already on GOV.UK. She showed the example of the page views to the “Make a SORN” page. The number of views increased by 70,000 in a month due to them simply adding a link to this page from the car tax related links section. Previously, SORN information wasn’t mentioned on the car tax page.

She also said they treat searches on the GOV.UK website itself as an indication that users haven’t found what they’re looking for first time. As an example, she said by looking at search terms she discovered lots of people were searching for information about taking rest breaks at work, and that they’d omitted that from the page about an employee’s contract and working hours.

Another example she gave was they’d found, on many of the pages about passports, people were searching for “second passport”. This was by people wanting to apply for a second passport. GDS has identified this as a topic that should be added to the site.

Lana said they also optimise the pages based on the language their audience is using. They found having the most important keywords in the title or first sentence helped people find information quickly. GDS uses analytics, Google Trends and Google AdWords to help them understand what terminology people use. For example, she said they found out their page on annual leave needed a better title: users were actually searching for “holiday entitlement”.

Finally, she said they also use the data to determine what to leave out. If a department wants to add new content to the site, they can use analytics to help assess if there’s actually a need for this content.

Lana’s presentation has been summarised in two excellent blog posts on the GDS website. They are well worth reading: