Posts in Category "Random Thoughts"

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.


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?

Tweet to Help

Some days back, I spotted a tweet by Tom Johnson announcing his new post – Podcast on the Seven Deadly Sins of Blogging. I know that I have been a sinner, not having updated my blog for over a month.
Nowadays, I spend a good part of my day keeping an eye on my Twitter home. My primary intent is to play the information facilitator for RoboHelp, the Adobe product I document. Twitter gives me the means to shout out updates, new tools, hidden features, and events.
I follow the power users of RoboHelp on Twitter and easily get information when they post new content on the web. My job then is to map that content to core Help topics and add the links so that other users can benefit from this supplementary content.

Step 1: Spot the announcement of a useful post.


Step 2: Identify the relevant topic in Help and add a link to the post.


Step 3: Tweet about the Help update.


Twitter gets me thinking – in different directions. Every now and then, I get derailed and something non-RoboHelp catches my attention. I spot ‘cloud computing’ and become curious to find out about what the world is thinking about documentation for SaaS applications.
Johnson’s posts reassured me that these occasional detours are a necessary part of the social networking experience that we are seeking as corporate tweeters and bloggers. They broaden our interests, update us on the trends, and prepare us to create relevant and interesting posts (being irrelevant and being boring are two of the seven sins Johnson talks about).
You can check out Johnson’s blog for the other five sins. Meanwhile, what are the seven deadly sins of tweeting?

MAX Awards Finalists

If you’re a multimedia enthusiast, don’t miss the entries chosen as MAX Awards finalists. Watch the videos selected in each of the eight categories and vote your favorite.
Voting ends on October 6th, at 12:00 noon PDT.

New Adobe TV

The well-stocked Adobe TV has always been a great source for learning Adobe products. The new version that went live a couple of days back is packed with cool new features that you’ll love. Here are some top ones:

• Customizable homepage
• Improved navigation and search
• Save your favorite episodes to “My Library”
• Share videos on social networking sites
• Subscribe to the RSS feeds of your favorite shows
• Pop-out video player to view videos at any size
• Commenting and rating
• Tags

Check out the latest on Adobe TV.

Adobe Help Events at MAX

At MAX next month, Adobe is putting together some sessions with snacks and drinks to get feedback on the new version of Community Help. Get a sneak preview. The new Community Help has an all new AIR interface and some exciting new features.

The sessions will be held at these times:
• Monday 10/5/09 11:30 am – 1 pm
• Tuesday 10/6/09 4:30 pm – 6 pm

Please contact if you think you can make either of these sessions at MAX and she’ll send you more details.

Adobe Community Publishing 1.1 beta

If you refer to Adobe documentation on the web, you know you can sign in with your Adobe ID and add your comments to any Help topic. Experts designated as moderators answer your queries.
With the release of Adobe Community Publishing 1.1 beta, Adobe has taken another huge step in encouraging community participation.
Community members can contribute tips, movies, code snippets and more with easy-to-use templates. Contributions are moderated by community experts. Plus, everyone in the community can rate and comment on contributions.
To add a contribution, follow these steps:

  1. Download the Community Publishing app:
  2. Author your tip using a simple template
  3. Publish it to

Content goes live within minutes and is automatically added to community help search.

Check out this useful tip added recently by RoboHelp moderator Peter Grainge.

For all tips, see

Frame, Rob, and Capture

Or, simply Help? Writing at Adobe, I can be envied for my easy access to some of the best authoring tools. On this page, I’ll be compiling nuggets of information that will supplement installed Help and help us become power users of FrameMaker, RoboHelp, and Captivate. Of course, every now and then, I will digress from the tool talk and talk authoring (authors will be another time and blog :)). Stay with me.