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.

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.

The roofer who makes £400/day because he read the Velux installation guide

Mark the Roofer came round to replace a broken tile on our roof late last week, and he told us that the Velux windows we’d had installed were fitted incorrectly. Apparently, up until two years ago, Velux windows needed to be fitted to the rafters, but now they should be installed onto a batten.

The consequence of fitting the newer style windows using the old method is they aren’t set high enough on the roof. The result is rainwater doesn’t drain freely, and is only held back by the surrounding felt. As the felt degrades over time (he said it’s usually two to three years), water starts to drip through into the room below.

The Velux installation guides and videos are actually very clear and well written, so it seems the reason why some builders seem to be installing the windows incorrectly is because they haven’t read the instructions in the last two years.

This roofer has read them, and makes a habit of checking any Velux windows he sees on the roofs he’s working on. It means he is able follow up many of his small £20 tile replacement jobs with larger £400 Velux re-installation projects. Sometimes, reading the manual pays.

Estimating production times for screencasts and elearning

Screencasts and video based learning content are growing in popularity, and we’re seeing a rise in the number of enquiries for this type of content.

Estimating the time required to develop this type of content can vary quite considerably. The easiest way to estimate the time required is to use metrics based on the duration of the screencast or video.

A simple walkthrough of a task or applications screen can take between 10:1 (ten minutes to produce  one minute of a screencast) and 100:1. The most generally quoted figure we’ve seen is 30:1.

If you want to add audio to your screencast, this is likely to be closer to 200:1. That’s because you’ll probably need to write a script, record the audio, adjust the audio quality, add the audio to the animation, and so on.

If you want to include video of a presenter, this will make the presentation look more professional, but it will mean you’ll need to allocate more time to development and production. In this case, you’ll be looking at a ratio closer to 300:1.You can reduce the time by using avatars (images of a presenter) instead of a real presenter. Adobe Captivate comes bundled with sets of avatars to help you do this.

Another factor is the level of professionalism you want to achieve. It can take time and effort to produce high quality audio and video. Lighting, in particular, can be a challenge. Adding quizzes and exercises will also have a significant impact on the time required. Creating your own music bed (a musical background to the narration) will also increase the time required. In the past, we’ve purchased audio background music files under licence, as it saved time.

What’s your experience? How long does it take you to create this type of content. Please share your thoughts below.

We’ve launched our online DITA self-study elearning course today

We’ve launched our online DITA self-study elearning course on the Cherryleaf website today.

This online training course teaches the basic skills, and provides an induction, in how to create content using the DITA XML standard. The learning modules in this course contain videos of the trainer with supporting slides and images.

Here’s a sample from the first module in the course:

This video is shown in a smaller size than you’ll see in the course. To maximise the video, click on the fullscreen icon (which looks like a computer screen) on the video player’s task bar.

Our plan is to offer online courses covering the fundamentals of different technical communication subjects, and classroom courses covering the more advanced aspects.

For details on the DITA course, see :

Cherryleaf’s online DITA self-study elearning course

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.