Author Archive: Nandini Gupta

Making Help popular and useful

A common refrain among software users is that the documentation or Help that comes with software is not useful. What’s more it’s boring. As a technical writer, when I receive this feedback, my typical reaction is emotional and, sometimes, kneejerk. That’s not the best way to deal with feedback we all know. So I wanted to step aside and take an objective look at why official documentation sometimes fails to meet user expectations.
In a recent article in Mashable, Mike Puterbaug, VP Marketing at MindTouch, argues why organizations should continue to invest in documentation. He says “documentation has become marketing’s secret weapon. Documentation is the language that accompanies a product, often outlining its development, design, technical language and marketing strategy in clear, definitive terms. Ultimately, good documentation won’t comprise a cost, but rather, a profit.”

What makes documentation or Help qualify as good?

Make sure that Help is findable
First and foremost, users should be able to find Help when they have a need. From a technical writer’s standpoint, promising findability is easier said than done. If the Help is hosted on the web, we must make sure that we continually revise and update the Help. A flat structure, an intelligent use of keywords and tags, and dense linking of Help topics and external content are must-have attributes for Google-friendly Help.

Serve content for both learning and troubleshooting
When creating and serving content, it helps to remember that users typically look for Help in two scenarios: when they want to learn and when they want to solve a problem. The mood and expectation of the users in one scenario is vastly different from the mood and expectation in the other. When users want to learn, they are patient and playful. When they want to solve a problem, they are time-constrained and ready-to-snap. The format of Help that works in the Learn scenario does not always work in the Quick Help scenario. For example, videos might not work as well as FAQs in the Quick Help scenario. The perception of Help as good or bad depends a lot on users in the Quick Help scenario. The trick is to track user feedback with rigor and optimize Help for these users who are looking for specific answers in Help.

Delight users with engaging strategies
It’s important to ensure that users find the format and presentation refreshing. Today’s users interact with a diverse range of applications. Because of the variety of devices that they use and the different purposes for which they use software, the software experience of most users today is rich. In this scenario, the over-templatized clinical Help needs to make way for something that has the power to delight. We need to relook at traditional learning theories, gather data on how users are consuming the content, and break the form intelligently. While our traditional Help formats serve as a robust backend, we need to devise and deliver new front-ends to serve Help. Visuals and multimedia play an important role here. Equally important is structuring and writing style, which as user feedback suggests, needs to be efficient and engaging at the same time.

Allow users to collaborate
Today’s Help must be social and collaborative. Today’s technical writer needs to engage with the user community and play a larger role of a community editor. Whether it is on the forums or on social media, interacting with the community helps us identify the top issues in the software that we are documenting and gather real-world examples. Instead of trying to document all that the software does or document every piece of content ourselves, we need to work with a content strategy that takes into account usage patterns and user feedback and includes content contributions from internal and external communities. Allowing users to evaluate the content (through social features, such as rating and commenting) facilitates a seamless churning that’s required to keep the most relevant content findable.

Act on usage data and feedback
Diverse user preferences are a reality. “Some users want to know the concepts behind a product before they use the product. Other users want to use the software without any preamble. You cannot please everyone, but if you know your audience, you can produce documentation that is useful and acceptable to most people.” The good news is that today we have access to a vast amount of usage data and feedback to know our audience. Page views, search data, context paths, ratings, and comments – all of these data points can help us understand what our users want.

In summary, making Help popular and useful requires a sea change in the way we create Help. The document development cycle can no longer end abruptly with a software release. Instead, it needs to continue well beyond a release and the phase that follows a release is an exciting phase for technical writers. In this phase, we need to engage with internal and external user communities and track usage data and feedback to enhance the core we delivered with input from different internal stakeholders. Our approach should be that of a web designer trying to make a qualitative improvement in the user experience.

Examples of new ways to deliver Help
Great visuals on a web 2.0 page – Inkscape tutorial
Content curated for learning and quick help – Digital Publishing Suite hub page
Community-powered support – Photoshop family feedback page


*The two quotes used in this article are from these references.

This article first appeared in the printed volume published for the tekom 2011 (tcworld 2011) conference.


#tcworld 2011 #tekom 2011

The big event of the tcworld event calendar, the tcworld annual conference, was held last month in Wiesbaden, Germany from October 18 to October 20. I had to deliver two presentations and conduct two tutorials. Thanks to an extremely disciplined and curious audience, those five hours turned out to be a rewarding experience for me. And when some of the attendees wrote back to share a few nice words … (by now, you must have guessed that I am no jetsetting ‘conferencer’).

More importantly, the three days gave me a chance to meet scores of technical communication and localization professionals. In the course of Q&A sessions, panel discussions, and informal chats, I learned about perspectives that usually come from working on different projects in different geos.

The content strategy track on the second day was a big draw for all of us who have been reading up about this trendy topic and even implementing it in some form or the other. The track, anchored by Scott Abel (Twitter: @scottabel), ran the entire day and as expected (see his Twitter bio), Scott was marvelous as the anchor.
In between my two presentations scheduled that day, I could catch the panel discussion and the presentations by Rahel Anne Bailey (Twitter: @rahelab) and and Joe Gollner (Twitter: @joegollner). Tekom has uploaded some of the presentations on the tekom-WebPortal. I strongly recommend checking out their slides.

On the last day, I randomly chose a presentation titled The Rhymes and Rhythms of Multimedia Localization and was thoroughly surprised. The presenter Maria Azqueta from Seprotec shared insights from a project in which she worked with more than 40 translators and reviewers to localize videos in 3 key languages and 4 dialects. I loved the audio samples and the quality of her presentation. Maria’s slides are also available on the tekom-WebPortal.

Next tcworld annual conference
October 23 to 25, 2012 same place

The Extras
Wiesbaden is a small picturesque city where the old and the new coexist beautifully. The conference venue was a stone’s throw from the hotel where I stayed. My stay was brief, and the days were spent in the conference. But the weather and the clean wide sidewalks were ideal for long walks, and I seized every opportunity to walk down to the city center.

More pictures

Scannable and visual docs

Someone once tweeted “Learners are always two clicks away from Angry Birds. And that’s why you’d better make teaching & learning engaging.”
The more I sift through user feedback, the more I get convinced that users today are in no mood to read long texty paragraphs. They want scannable and visual presentation of information. Keeping this in mind, we are trying to enhance our knowledgebase articles and Help pages, especially the ones that are most-viewed.
I shared some examples of this initiative in the tekom conference last month at Wiesbaden, Germany.

Example 1

This document is one of our most-read knowledgebase articles. Over the years and over many updates, it had become an information dump. In an effort to cover all scenarios, reported by users over the years, readability and findability suffered. A complete revamp was done, and you can see how instructional design strategies, such as branching and chunking, were applied to transform a long linear doc into a visual doc.

Example 2
Adobe Illustrator type tools

In this example from the Adobe Illustrator documentation, graphics and intelligent structuring are used to present information in a visual and easy-to-scan layout. Detailed information has been layered to allow for different user levels and needs.

Do you have any example of visual docs? Any example of scannable and visual docs that do not have graphics?

Two best practices from RoboHelp 9 sample projects

Some days back, I had blogged about the two sample projects that come with Adobe RoboHelp 9. While the primary purpose of these projects is to demonstrate some of the new and old features of RoboHelp, these projects also exemplify some cool best practices for authoring in RoboHelp.

Use of cross-hatching to indicate that a topic/text has CBTs applied

Using the View > Show > Conditional Areas option, the sample projects display CBT-applied topics or text with cross-hatch shading.

Cross-hatching to easily identify CBT-applied topics

Cross-hatching to easily identify CBT-applied topics

See Hide and view conditional text for more information.

Use of DHTML drop-downs to reveal information on demand

The sample projects include several tips. Some of the tips are “hidden” in the output by using DHTML drop-downs. Only the tip icon appears in the output to minimize distraction, and users need to click the icon to reveal the information. The same technique has been applied to show information about entitlement, procedure, and disputes related to dependants’ leaves.

Extra information "hidden"

Extra information "hidden"

Extra information displayed "on demand"

Extra information displayed "on demand"

See Dynamic HTML and special effects for more information.

We recommend that you play with the sample projects and discover many more best practices. Check out how you can use user-defined variables and snippets to enhance productivity and ensure consistency. Check out how you can use master pages to add branding and copyright information to each page of your Help system.