Your user guide writing questions answered

On a future episode of the Cherryleaf Podcast, we’ll be answering the top 20 most popular questions on writing user guides.

You can submit your question via our contact form or record your question by voicemail, using the button below.

Potential questions include:

  • How do I write  a user guide?
  • Why create user guides today?
  • What is user guide?
  • Can I animate user guide?
  • User guides versus training manuals
  • Is there a difference between a user guide and user manual?
  • Should I create a user guide manual template?
  • The time needed to create a user guide
  • Can I clip and reuse sections of a user manual?
  • How do I create an outline for a user manual?

When Mercedes made emotional owner’s handbooks

In this week’s Autocar magazine, Chris Goodwin bemoans the fact that Daimler AG has taken the romance out of its owner’s handbooks.

He refers to the handbooks for Mercedes cars built in the 1980s, and how they congratulated the owner on their wise decision to purchase an expensive, high quality car:

1980s Mercedes handbook

Continue reading “When Mercedes made emotional owner’s handbooks”

How the new Kindles might affect the role of the Technical Author

Here are some initial thoughts on how the new Kindles from Amazon might affect the role of the Technical Author.

Yet more diversity in reading platforms

Technical Authors know this already – their content needs to work on lots of platforms and across different mediums. It’s more evidence that the layout must not be baked into the content; if the two are controlled separately (by using cascading style sheets to modify and adapt the layout), then we can publish to lots of different devices. Technical Authors do this today, but it’s still worth mentioning.

The distinction between video and text based information is likely to become blurred

The Kindle’s new Whispersync for Voice feature means that users can switch between reading and listening. If this extends into the narration of video, in the future, we could see users toggling between text-based content and video tutorials. With the text and the narration synchronised, the video could start from the last word the user was reading. Mozilla’s Popcorn maker project could make this possible across all tablets, not just the Kindle.

Video may be come less serial and more hypertext-like

Amazon’s X-Ray for movies enables users to navigate and explore a video by characters:

Simply tap on any scene to instantly see which actors are currently on screen, jump straight to other movies in which they star, and more.

Wouldn’t it be great if this could be applied to video-based tutorials? For example, you might stop a clip on installing a product to see which tools you need, and then navigate to the other times when you might also need to use that tool.

The time spent reading may increase

Each year, the ability to have hundreds of books on your person, ready to be read at any time, increases. What’s more, with the passive screen technology, people can read “online” material for longer.

Reading will become a more collaborative experience

The Kindle encourages users to share passages and notes on a book. In the future, it may become the norm for you to read a user manual and share your experience with other readers of the same guide.

What do you think?

Hyundai uses an iPad as a driver’s manual

According to Hyundai USA

There’s nothing worse than buying a new luxury car only to sit down and have to learn about it through a boring owner’s manual. Thankfully, every Equus comes with a 16GB WiFi Apple iPad, and instead of the boring owner’s manual, the Equus Owner’s Experience app teaches you everything you need to know through demonstration videos, interactive product and safety demonstrations.

Hopefully, you won’t ever need it when you have a flat battery.

The User Manual 2.$

Here is an interesting interview between Robert Scoble and Aaron Fulkerson of Midtouch on how MindTouch’s technical communication software is changing how people work together at big companies.

“We started seeing more and more of our customers—Intuit and Microsoft, Intel and Autodesk and Mozilla – launching these documentation communities where they have a body of content for user manuals,” explains Fulkerson. “Just imagine taking ten DVDs of video and text and putting it on the internet for the first time. What does that do for your search engine optimization? And then building a community around that where [customers] can contribute to it. They’re registering with the site, they’re sharing information with you about how you can improve this or that—of course it’s helping lead generation.”

“Enterprise wikis and documentation communities may sound like rather different applications, but Fulkerson asserts that they’re actually the same use case—they’re just applied to two different things. “One is internal around enterprise systems, the other one is external more around social media sites. But they’re both delivering collaboration and social capabilities in a web-based environment that’s connecting systems together.”

Contact us if you’re interested in looking into Mindtouch’s software.

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.

Should we offer a workshop on documentation as a emotional experience for users?

We’re presenting on documentation as a emotional experience for users at the TCUK conference later this month, and we’re considering whether we should develop this 40 minute presentation into a workshop.

Technical documentation written today really doesn’t take into account the different states of emotion users can have, and this can lead to users bypassing it completely. It’s important to recognize a user’s “state of mind” and deliver content that is best suited to that state. It may also be useful to use techniques that can transition users from one state to another.

So, would you be interested in a workshop on this subject? Please let us know.