How to create online Help topics that are editable by clients

In the Agile Technical Writers forum on LinkedIn, one of its members posted this question:

“I need to create an contextual online help for an complex web tool (ok, that´s not that hard). The customer must be able to add some specific job instructions to this online help by himself. The customer part must not be overridden when the online help is updated.”

LinkedIn’s forums provide limited functionality for long replies, so I thought I’d answer the question in more depth on our blog.

There are three main approaches you can take:

  1. Transclusion
  2. Appending content to the bottom of a page
  3. Embedding empty placeholder topics within topics (which the client can use to add content)

You can also simply link to an external topic. However, in this case, they wanted the user content to appear with the official content.

Transclusion

In the DITA authoring standard, transclusion is called content referencing (or conref for short). It enables you to insert information from one topic into another. This means you can add customised content to a topic without having to make any changes to that target topic. You specify how the information is pushed into the existing topic: Insert the information just before an element;  insert the information just after an element; or replace the information contained in an element. One of its strengths is, if you are adding new items to a list of steps, the list will renumber automatically.

Here is an illustration from our DITA training course:

conref example

The downside is writers need to be familiar with DITA, or be given a template to use.

Appending content to the bottom of a page

A common approach is to enable users to add comments and additional information at the bottom of each topic. This is the approach taken by tools such as Confluence, Mindtouch and MadCap Pulse.

madcap pulse main screen

This can work well. However, the information can be missed by it being at the bottom of the page, and if there are too many comments.

Embedding empty placeholder topics within topics

Another approach is to have empty topics within each topic. The two topics can be concatenated (joined) together to form a single topic. The client can add any client-specific content into the empty placeholder topic, so they don’t need to touch the topic containing the official content. This is sometimes called embedding topics within topics.

Here is an example of how local branch information is added to official documentation on fire safety procedures:

embedded topic example

The advantage of this approach is that it can be done with simpler authoring tools than DITA (like markdown). The disadvantage is that you may not be able to preview the final topic (to do that, you’ll need to generate the whole document), and it won’t work as well for inserting content into numbered lists.

Do you use a different method?

Please share your thoughts below.

Microsoft’s “No more robot speak” in action

 

Our post about how Microsoft is changing its writing style (Microsoft moves away from “robot speak” in its user documentation) generated a lot of interest, so I thought it might be useful to post some examples of it that we’ve spotted.

These examples are from Office 365 Premium Edition.

Continue reading

Changing times in technical communication 3 – The long form Help topic

New York Time snow fall article imageOne of the most recent developments in web page design has been the introduction of “long form” web pages. Will we also see the long form approach used in Help, or perhaps start to influence the way some Help pages are designed?

Continue reading

Google adds conversational search-by-voice to Chrome’s Help

Chrome Help Search window with microphone optionGoogle has updated Chrome in build 27 to include conversational voice search, and this feature extends to the Help pages.

According to TechCrunch, it transcribes your queries in real time. It also lets you use natural language, asking Google straightforward questions and getting straightforward answers, both read back to you by dictation and in actual Google search results.

Based on a few initial tests, for South East English accents, it works really well.

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

Introducing the Head Up Display. Say hello to the future of the menu

The Ubuntu operating system is to replace its application menus with a  “head-up display” (HUD) box. According to Mark Shuttleworth, Lead design and product strategy person at the company behind Ubuntu:

We can search through everything we know about the menu, including descriptive help text, so pretty soon you will be able to find a menu entry using only vaguely related text (imagine finding an entry called Preferences when you search for “settings”).

 

One of the comments states:

I suspect that applications will need to give help documentation a more significant place in the development of the application than it currently enjoys. Help seems the logical place to embed command discovery in such a system especially in connection with a capacity for fuzzy searches.

UAEurope 2011 conference review

UAEurope 2011 was possibly the most enjoyable and interesting conference in its long history.

Sonia Fuga of Northgate explained how they are using DITA, WordPress and Web 2.0 features to streamline the documentation process, simplify the review process and deliver interactive context sensitive Help for one of their larger applications. Delegates were interested in how their new Help included Google-like search results (produced by referencing DITA elements within the topics) and the ability for users to provide feedback and obtain notifications of content updates via RSS feeds.

Leah Guren presented her research into to the cultural dimensions of software Help usage. Her insights into the use of (and opinions towards) Help by beginners and advanced users were fascinating and counter-intuitive.

My presentation on applying games techniques to User Assistance seemed to have been well received.

In a number of presentations, there was the recognition that many users now go to the search engines when they get stuck. For those that can publish their Help on the Web, this poses no great problem. However, for those who are unable to do this (for confidentiality, security, legal or other reasons), they face the challenge of how to guide users away from the search engines and towards their Help. There were a number of approaches presented, and I suspect this issue will be raised and discussed again at future conferences.

On the Cherryleaf stand, located in the exhibition area, we were giving away cherry Sencha leaf tea, leaflets and some stickers. The stickers proved far and away the most popular.

Help is broken?

Are we at the point when we need to acknowledge that classic online Help files are not working as well as they should – that is, as the primary source of information to assist users when they get stuck?

This is not a Don Draper “why I’m quitting tobacco” moment, and this is not a criticism of the Help Authoring Tool vendors. Instead, it’s a proposal that, in some situations, what is delivered as online Help needs to be substantially modified to meet the needs of many modern technologies and users.

What’s wrong with Help? Help is often a “walled garden” in an Internet-era built on knowledge sharing and collaboration. Usability in relation to the user interface can be poor at times. It’s hard to measure its value and the ROI. Even its purpose can be vague to some project managers. Unfortunately, there’s often just not enough time to make significant improvements. We could go on.

Many users still get stuck, and many products still fail to work when they’re linked to another. Words still are a key way of communicating and teaching users. We still need to assist users and we still need some form of Help. It could be a useful tool in “evangelism marketing”. It could do so much more. This is why we’re suggesting it’s time to take a strategic look at what and how we can provide Help for when users get stuck.

What do you think?