Posts tagged "trends in technical writing"

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

Reference
http://mashable.com/2011/08/12/product-documentation-marketing/
http://www.techscribe.co.uk/techw/good-documentation.htm

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

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