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.

What’s New in Adobe Captivate 5

Smitha V, Adobe Captivate content lead, shares this overview of key new features with links to Help:

Adobe Captivate for Mac
Adobe Captivate 5 is available on Mac OS. Both Adobe Captivate on Mac and Adobe Captivate on Windows have identical features and homogeneous user interface.
For Mac-specific details and system requirements, see the product website.
See for an overview of Adobe Captivate on Mac.

Optimized User Interface
Improve the overall authoring experience with Property Inspector that provides an in-context list of attributes when objects are selected. Work simultaneously on multiple projects using the multiple-document interface. Personalize workspaces and switch between them as and when needed. Benefit from a user interface that is consistent with popular Adobe applications such as Adobe Flash, Photoshop, and Dreamweaver.
To know more about the new user interface of Adobe Captivate, see Adobe Captivate 5 Online Help. Also, watch the videos at and

Object Styles
Quickly obtain a uniform and consistent formatting for objects by defining styles and applying them. Reuse the styles across multiple Adobe Captivate projects without having to recreate them.
For more information on object styles, see Adobe Captivate 5 Online Help. Also, watch the videos at and

Master Slides
Use Master Slides to easily create and maintain well formatted and consistent-looking content that meets corporate guidelines. Make project-wide formatting changes conveniently and consistently.
To learn more about master slides, see Adobe Captivate 5 Online Help. Also, watch the videos at and

Rich Animation Effects
Create rich object animations within Adobe Captivate 5, by combining predefined effects such as straight-line motion, rotation, and glow. For added impact, seamlessly import custom animation effects from Adobe Flash® Professional.
To know more about animation effects, see Adobe Captivate 5 Online Help. Also, watch the videos at and

Multi-Video Support and Synchronization
Include videos in your content without having to use another application. Import videos in a wide variety of popular formats (AVI, MOV, FLV, MPEG) and synchronize video with a project, slide, or a set of slides.
To know more about multi-video support and synchronization, see Adobe Captivate 5 Online Help. Also, watch the videos at and

In-Context Learner Collaboration using Twitter
Use the Twitter widget to create courses that let learners collaborate with each other as well as with the author using their Twitter account. The learners can ask questions, get answers, and access preexisting discussions.
The Twitter widget will be made available soon on the Adobe website. So, stay tuned.

Collaboration and Review using
Enable multiple authors to work simultaneously on a project by hosting and sharing projects on Also, host projects on for shared reviews to enable authors obtain collective review comments from reviewers.
To know more about collaborating and setting up reviews using, see Adobe Captivate 5 Online Help. Also, watch the videos at and

Tracking and Reporting without an LMS
Meet basic evaluation needs at no extra cost by tracking and reporting key performance metrics, such as average score and pass or fail, without having to invest in a Learning Management System.
To know more about tracking and reporting without an LMS, see Adobe Captivate 5 Online Help. Also, watch the videos at and

Expanded Asset Library
Get a larger set of prebuilt widgets, playbars, skins, stock animations, images, text captions, and buttons with superior aesthetics and usability.
To know more about these objects, see Adobe Captivate 5 Online Help. Also, watch the videos at

Adobe Photoshop Round-Tripping
Instantly update Adobe Photoshop files imported in Adobe Captivate projects. Adobe Photoshop can be invoked from within Adobe Captivate. If source files are directly updated in Adobe Photoshop, synchronize the linked file in Adobe Captivate with its source using a single click.
To know more about animation effects, see Adobe Captivate 5 Online Help. Also, watch the videos at and

Adobe Flash Round-Tripping
Instantly update Adobe Photoshop files imported in Adobe Captivate projects. Adobe Photoshop can be invoked from within Adobe Captivate. If source files are directly updated in Adobe Photoshop, synchronize the linked file in Adobe Captivate with its source using a single click.
To know more about round-tripping to Adobe Flash, see Adobe Captivate 5 Online Help. Also, watch the video at

Record Applications from Flash
Record applications from within Flash without having to switch to the Adobe Captivate interface. For more information on the workflow, see Adobe eLearning Suite 2.0 Getting Started Guide.

Adobe Soundbooth Round-Tripping
Edit audio files in Adobe Captivate projects by invoking Adobe Soundbooth from within Adobe Captivate. To know more about round-tripping to Adobe Soundbooth, see Adobe Captivate 5 Online Help. Also, watch the video at

Round-tripping from Adobe Captivate to other products, such as, Adobe Photoshop, Adobe Flash, and Adobe Soundbooth is available only when these products are installed using the Adobe eLearning Suite installer. You cannot round-trip to these products if they are installed as point products or as part of Creative Suite 5.

Adobe Captivate 5 and Adobe eLearning Suite 2 Resources

Today is a big day for some of my favorite Adobe products. Having spent six years of my career in offshore CBT factories learning and implementing e-learning strategies (is Kurt Miles still around?), it’s not surprising that I am a wee bit more attached to Captivate and eLS.

New versions of these products are being shipped today and, finally, Captivate and eLS users get a chance to ‘play’ with these tools (links to download trial versions at the end of this post).
Ever since the new versions were announced, Twitter has been abuzz with queries about when they would be available in the store.


The good news for all users waiting to try new versions of Captivate and eLS is that Adobe Learning Resources and power users like R J Jaquez (@rjacquez), Allen Partridge (@AdobeELearning), Michael Lund (@cpguru_com), Mark Fletcher (@macrofireball), Kevin Seigal (@Kevin_Siegel), and many others have created several resources that should help you get started. We have tried to make some of these available to you from the Captivate and eLearning Suite Help & Support pages. It’s a good idea to bookmark them.

I am also listing a handful of resources here:

Core Help

Videos and Articles
End-to-End eLearning Development with Adobe eLearning Suite 2/
Adobe Captivate 5 for New Users/
The New UI in Captivate 5
Animation Effects
Master Slides
The New Effects Feature
Object styles will shave hours off of your development time!
Adobe Captivate 5: Quickest Quizzes Ever!
Constructing Test with Multiple Results (CP5)
Using Advanced Actions (CP5) to show conclusion, based on multiple scores
Widgets and the Widget API
A quick look at text to speech in Adobe Captivate 5
Leveraging the Cloud in Adobe Captivate 5

As you use the product and the resources, do share your learning with other users by commenting in the Help.

Download trial version of Captivate 5.
Download trial version of eLearning Suite.

More details about the products here.

Undo History panel in Photoshop Elements

Every time you make a pixel change in a photo, Photoshop Elements saves the state. You can jump to any of the last 50 (default and configurable) states by selecting the state in the Undo History panel and start working from it. You don’t need to save a change in order for the change to appear in the history.


If you can’t find the Undo History panel in your workspace, open it from the Window menu.

For more information about the Undo History panel and a set of guidelines, see this article in Photoshop Elements Help.

Story of the missing History brush

I was analyzing a search report for Photoshop Elements Help this morning. One of the instances of a high bounce rate (highlighted red in the report) was for ‘history brush’. I searched for ‘history brush’ in the Help PDF and found zero results.

Well, I am a new user of Photoshop Elements. And that’s the reason I expected it to be defined there. Had I been familiar with Photoshop Elements (and Photoshop), I would have instead googled for ‘history brush’. And that’s what I did next.
The scenario is crystal clear now. Photoshop users who are aware of the power of the History brush in Photoshop look for the tool in Photoshop Elements.

The History brush does not exist in Photoshop Elements.

The History Brush is useful for performing photo editing tasks, but it’s also a tool that can save you when you encounter one of those “Oops, I didn’t realize I’d done that” moments.

Has anybody figured out a way to simulate the History brush in Photoshop Elements?
Yes, of course. Here’s a list of resources to help you understand and experiment:

If you are a new user like me, let me know how easy or difficult it was for you to simulate the Photoshop History brush functionality with layers in Photoshop Elements.
And for those Photoshop users who are looking for a History brush in Photoshop Elements, I need to do something more. Because they are limiting their search in Help, I need to find the right place(s) in the Help and tell them that the History brush is not available in Photoshop Elements and point them to workarounds (pretty much what I have said here).

SEO – the challenges of a new-age writer!

I can’t see Flash content on Windows 7

I haven’t yet had a chance to work on Windows 7. Although for many months now, I have had some second-hand experience of using it. The developers I work with, my coworkers, and my tweples – everyone’s talking about Windows 7 on the other laptop or the new PC.
Apart from substantiating the general euphoria about the interface and the speed, the comments or the tweets sometimes highlight pain points, many of which are compatibility issues and have a quick fix or workaround.
In a recent blog post, Rick Stone talks about one compatibility issue that our Help users are likely to encounter. Many HTML pages have Captivate demos inserted in them. If you are running Windows 7, you might find that these demos are not appearing (instead, there’s a large placeholder).

Cause and Solution
Flash Player is currently not supported on 64-bit browsers. Use a 32-bit browser.
For more information, see this document from Adobe KnowledgeBase.

To share his experience with RoboHelp users, Rick has added a link to his post in the relevant topic in RoboHelp Help.

If you have encountered any problem testing RoboHelp output and found a solution, share the information with other users by adding a comment.

Pin a project for quick access

By default, the list of recent projects that appears in the Starter pod and in the File menu displays up to the last ten projects opened. Pin a recently opened project so that it always appears in the recent projects’ list. The list displays the pinned projects and recently used projects up to the number of projects set in the Max field.

  1. Select Tools > Options.
  2. On the General tab, select a project from the Most Recently Used list.
  3. Click Pin. Click Apply.

Click Unpin to remove a pinned project from the recent projects’ list.