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 “Design-led technical documentation”

The ideal length for instructional screencast videos

Screencast videos have become a popular means for delivering “how-to” information. One of the questions developers must address is, how long should you make your screencasts?

Axel Luterh SAPAt last weeks’s tekom conference, I saw an interesting presentation by Melanie Huxhold and Dr Axel Luther of SAP on how they develop screencasts for SAP’s products (Produkt- und Lernvideos als ideale Ergänzung zur klassischen Dokumentation). In their presentation, Melanie said they had determined the ideal length for their videos by sending out a questionnaire to users, asking them what they preferred.

Continue reading “The ideal length for instructional screencast videos”

The over optimistic user

On Dara O’Brien’s Science Club (BBC 2) this week, neuroscientist Dr Tali Sharot explained “Optimism Bias”, suggesting that our brains may be hard-wired to look on the bright side.

Here is her TED presentation on the Optimism Bias:

Nearly everyone is optimistic they will never get divorced, and they are an above average driver, when statistically that’s just not possible. It seems reasonable to infer that users of software are  also over optimistic, believing they are an average or above average user in their ability to use an application.

This has an implication for those developing user documentation and training. It seems likely that most people will believe they don’t need to read the documentation (or receive training) when they actually do.

Reducing app abandonment

app abandonment - app store imageAt the UAEurope 12 conference, SAP’s Keren Okman quoted a shocking statistic: that the average mobile or tablet app* is used an average of just 3-4 times by a user.

The issue of “app abandonment” is one that is likely to be of greater concern for software developers in the future, as they invest ever increasing amounts of time and money into developing apps for tablets and mobile devices.

Keren said SAP’s response has been to get their Technical Authors involved in writing the product descriptions displayed in app stores. This is the information people read before deciding to purchase. They plan to rewrite these descriptions and provide more guidance on how to use the produce before customers get started.

In the same way that developers are now considering a “mobile first” strategy when they develop new software and web sites, we may be seeing the beginnings of a “Help first” strategy as well.

A “Help first” strategy is where developers abandon the belief in the totally intuitive app (one that sells itself, requires no online Help and only needs limited support) and recognises the limitations of mobile operating systems require Help/User Assistance to be designed into the application from the very outset of the project planning.

To prove this, developers can use A/B testing to reduce app abandonment and evaluate how much User Assistance is needed.

Unfortunately, if app developers leave the planning for Help to the end, then their app has probably already failed.

*App is a term used for software applications for mobile and tablet devices.

Does looking at online Help make users forget?

Treasury at Petra, JordanOver the weekend, Dr Chris Atherton suggested I look at “the doorway effect”. You may well have experienced walking through a doorway and then finding you’d forgotten why you’d stood up in the first place.

Researchers at the University of Notre Dame have discovered your brain is not to blame for your confusion about what you’re doing in a new room – the doorway itself is.



From Scientific American:

The researchers say that when you pass through a doorway, your mind compartmentalizes your actions into separate episodes. Having moved into a new episode, the brain archives the previous one, making it less available for access.

The doorway can be a virtual doorway as well as a physical doorway. The researchers’ experiments involved seating participants in front of a computer screen running a video game.

So is this effect also happening when users need to leave a screen in a software application and read Help – be it delivered as a .CHM file, on a Web site or on paper?

The solution? If we deliver User Assistance (Help) in a way that it is actually located within the application screens, not only can we minimise the need for users having to go through a virtual door, we can also embed the learning into the users’ specific situations.

More: Scientific American article

Measuring the value of Help in desktop applications

One of the challenges for Technical Authors is quantifying the value of what they produce. For example, how can you tell how many people are reading online Help when the software is installed on someone’s desktop computer? One application mentioned in passing as last week’s UAEurope conference, ApplicationMetrics, might be able to provide the answer.

ApplicationMetrics collects usage and platform data, behind the scenes. It’s a product that is no longer being developed any more, but you can still download it. It may enable you to collect “operational funnel” data that’s similar marketing funnel data – test and track whether users are going to the help and resolving their issues.


Towards Flow-Based User Assistance

Flow theory is a psychological concept that is gaining interest in e-learning. It is a concept that should be also considered in the fields of User Assistance and Technical Communication.

Flow is akin to sportsmen being “in the zone” – flow is the situation where people are happiest when they are completely engaged in a task.

Online Help has been traditionally interruptive – people have to subconsciously admit they have failed and need to seek assistance from a Help file, Web page or user guide. The adoption of the term “User Assistance”, instead on online Help, is part of movement towards new models for minimising the situations where users get stuck, helping them quickly should that happen.

The conditions necessary to achieve the flow state include:

  • Having clear goals
  • Direct and immediate feedback
  • The right balance between the user’s ability level and the task
  • An activity that is intrinsically rewarding.

Flow-based User Assistance complements concepts such as adaptive content, as it implies content should adapt dynamically to explain information in the most suitable way. It also complements ideas such as affective assistance, conversation and community based documentation, in that these may be a more suitable “tone of voice” in certain circumstances.

In practice, this means that User Assistance is likely to be embedded into the User Interface – for example, helping explain what certain concepts mean, and what makes a good choice.

It is a very good approach to take if you are developing apps for mobile phones or tablets. This is, in part, because the iOS operating system has limited multitasking capabilities – you have to interrupt one activity in order to do another.

To adopt a flow-based approach, User Assistance must be planned and considered from the very start of any software project. As it is not a bolt-on to the application, it cannot be left to the end of the project. Guidance text becomes located in numerous different places.

The reward for taking this approach is that users get stuck less often, enjoy the application more and become more capable users, perhaps even at peak performance.

Designing documents for the iPad 3: the return of old design metaphors

After a few days of using the new iPad 3, it seems likely that, in the future, documents will be designed to take advantage of its retina display. Below are some thoughts on the new trends we’ll see in the way documents are designed for reading on tablet devices.

The paper metaphor

It has been good practice to present information published on paper and information published on screen differently. The limitations of computer screens, (for example, the screen resolution, screen flicker and eye strain issues) have meant long, linear documents don’t work on a screen. People like the resolution, portability and ability to make notes that paper provides. Paper simply is a great medium for deep learning and reading on the move.

It means organisations expect PDFs to be read on screen, when in reality they are printed out by users. Often the promised printing savings by distributing content online were never actually realised.

With the iPad 3’s screen, most of the limitations of reading on screen have been eliminated. Indeed, Apple is promoting it as a device for reading textbooks – which is can be an example of deep learning. It’s like paper in that it’s portable, you can make notes and you don’t get eye strain.

This means, we’re likely see documents on screen that look like documents printed on paper. It may be time for Technical Authors to dust off that copy of “Dynamics in Document Design”! For books that use Apple’s iBooks, we’ve found you tend to read page by page, instead of using the “peck and scan” approach common reading online content.

A new metaphor for online documents – Metro

The paper metaphor is not the only metaphor you can use. The new Metro UI, developed by Microsoft for Windows 8 and smartphones, is another design metaphor that is being adopted.

The Metro UI uses the following approaches:

  • Information is consolidated groups of common tasks to speed up use. This is done by relying on the actual content to function as the main UI.
  • The result is an interface that uses a “grid approach”, using large blocks (instead of small buttons, as well as laterally scrolling “canvases”.
  • Page titles are usually large and scroll off the page laterally.
  • The UI responds to users actions, by using animated transitions or other forms of motion.

An example of this is the Guardian iPad app:

According to The Guardian’s Andy Brockle:

We have created something that is a new proposition, different to other digital offerings. It works in either orientation and nothing is sacrificed. Instead of it being based on lists, breaking news, and the fastest updates it’s instead designed to be a more reflective, discoverable experience.

Displaying images

With the ability to pinch and zoom, readers have the ability to look at images in great detail. This may mean writers will need to present their documents in SVG format, but if we assume they stick to bitmap formats such as .jpg and .png, we’re still likely to see a change in the way documents that rely on images are designed. Instead of needing a series of separate images to display detail, the writer can provide a single image for the reader to explore. It also seems likely we’ll see images that contain “layers” that can be peeled off to reveal the underlying details.

Unresolved aspects

We’re at the beginning of the process of making the most of portable devices with “real-life” displays, so document design is likely to evolve further. It’s still unclear what is the best navigation UI for iPad3 readers.

The bear trap

There is a huge bear trap waiting to catch out organisations – that they assume what works on iPad 3’s retina display will work on screens with lower resolutions.


The more you use the iPad’s new screen, the more you realise it will change the way documents are designed in the future – the biggest possibly being a move from on screen content being structured laterally instead of vertically. With predictions of there being more iPads than citizens of the United States of America by the end of next year, there’ll be more and more reasons for optimising content for the iPad 3.