WritersUA - Training and Information for User Assistance Professionals

Key Trends in Software User Assistance

By Joe Welinske, WritersUA

Bookmark and Share

This is the first of a two-part series discussing the current and future issues associated with software user assistance.


Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

What Is User Assistance    Link to contents

User assistance helps to improve the experience of a user when working with software. This can include describing the user interface, but also focuses on how to help the user to best apply the software capabilities to their needs. User assistance can be considered a component of the broader category of user experience.

User assistance employs a number of devices including, but not limited to, Help, wizards, tutorials, printed manuals (and their PDF equivalents), and user interface text. User assistance professionals also contribute to enterprise knowledge-bases and content management systems.

Effective user assistance development requires a variety of communication skills as shown in Table 1. One of the more enjoyable aspects of user assistance is the opportunity to work in an interdisciplinary atmosphere. Most UA professionals wear several hats and will be involved in many, if not most, of the skills shown.

Writing skills and editing are foundation elements for most user assistance professionals. Generally these skills are acquired through educational programs at universities and community colleges. Other content development skills include task analysis, the interviewing of subject matter experts, and indexing. These skills are most often learned on the job from colleagues.

In addition to creating the content, we also need to review and help design all aspects of the communication between our software products and the user. Progressive UA is very dependent on testing our designs before and after they are put into action. Making the right adjustments to user interface text can often reduce or eliminate the need for more involved types of user assistance. With large-scale documentation sets, it is very important to understand how to properly design and implement information systems.

Ultimately, almost all user assistance components take the shape of digital deliverables. With the exception of printed materials, all of our words and images need to be transformed into an electronic format and integrated with the software product and its environment. Because of this, user assistance tends to require an interest and affinity for technology amongst its practitioners. Whether it is working with authoring tools, or doing format conversions, or delving into advanced programming, the UA professional is always involved with technical activities.

The size and nature of our organizations can create additional responsibilities for UA professionals. Large documentation repositories with hundreds and thousands of topics makes content management a key skill for many of us. When software is translated into one or more languages, source control and efficient writing processes become extremely important. Many organization have formal testing procedures for digital deliverables that can affect UA development. Making our products accessible for users with physical and situational disabilities is a growing area of competency. We also need the skills to create effective moving and static images.

Table 1. The User Assistance Skill Set

Content Digital Rendering
  • Writing: Procedures, Reference, Wizards, Embedded, UI
  • Editing: Copy, Technical, Developmental
  • Task Analysis
  • SME Interviewing
  • Indexing, Search
  • Coding Online Help: CHMs, Web Help
  • Coding Web Content: HTML, XML, CSS, JavaScript
  • Programming: C++, php, Perl, Ajax
Design Other Key Activities
  • Usability Testing, User Interface Design
  • Instructional Design
  • Information Architecture
  • Schemas, Ontologies
  • Content Management
  • Localization, Translation
  • Quality Assurance, Testing
  • Multimedia Development
  • Images, Videos
  • Accessibility

Most Valued User Assistance Skills    Link to contents

WritersUA conducts many surveys about user assistance topics. The 2011 WritersUA Skills and Technologies Survey took a look at several issues of importance to user assistance professionals. One of them was the skills that we value most highly in our daily work. The results are shown below. The top vote-getter was "expertise with authoring tools" with 85% of respondents valuing that highly. This extremely high reliance on tools has many ramifications for us. One is the number of features available to us and the ability of those features to help us accomplish our UA goals. The Adobe Technical Communication Suite has addressed this issue by providing an integrated set of tools available at a price that fits the budget of most tech comm organizations. When using a variety of tools it is always helpful when our source files can be seamlessly shared between those tools.

In the Skills survey,you can also see that content development has a strong presence. Writing Procedures, Interviewing, Task Analysis, and Writing Reference Information are valued highly. Attention to content development is made easier when the tools we use allow us to focus on the words in our topics and books rather than formatting, file types, and source management.

Content reuse (also known as single-sourcing) is an important process for many organizations. The relatively high cost of creating quality information can be tempered by leveraging that content across multiple deliverables. For example, a knowledge-based article written about printing a monthly report could be used in a context-sensitive Help system, a PDF user guide, and an employee training seminar. The use of conditional tagging allows us to fine-tune the information for individual deliverables, including supporting different versions of the same product. Both RoboHelp and Framemaker provide exceptional handling of content reuse.

Most Valued User Assistance Skills

An important development process associated with content reuse is structured authoring. This is a template-based method of capturing and organizing content right at the moment of creation. With this method, linear, free-form documentation is replaced with fixed field data entry screens. An information architecture team identifies what types of information is required and then customizes the authoring environment to accept and validate the information as it is entered.

One of the benefits of this method is that the content is separate from the presentation. Definitions, procedures, and links are saved as individual data elements that can be assembled later for distribution. While the data is generally stored in an XML/SGML format, authoring tools and content management systems control the markup behind the scenes. Style sheets are created to transform this content data into the desired deliverable - whether that is HTML Help, PDF documentation, DocBook, or web pages. Frameworks like DITA can be used to customize the authoring and delivery of content for a variety of very specific purposes. Tony Self of HyperWrite likes to refer to this as WYSIOO - What You See is One Option.

Structured authoring keeps our focus on writing and design. It also makes it easy to tag content for different purposes, including single-sourcing, search, and the generation of hierarchical list and tables.

The benefits of structured authoring come with costs. Migrating to this system of authoring requires new tools and a commitment to embracing a different style of content creation. Technical writers need to be trained in how to deal with the challenges and opportunities of a structured authoring environment. For smaller teams it can be a relatively quick and smooth transition. In larger organizations, it requires full support from management, significant investment in new resources, and a lengthy migration period.

Adobe Framemaker explicity supports structured authoring and DITA. RoboHelp offers easy integration with Framemaker styles and the direct import of DITA maps.

The user assistance world continues to evolve. There are several areas where technical communication professionals are branching out into new skills and deliverables. These include:

  • Writing or editing magazine-style articles. Help topics are great for providing quick answers to questions, but less useful for more involved conceptual information. Magazine-style article introduce customers to important features using a story-line and more conversational writing style.

  • Writing or editing blogs. More progressive organizations are using blogs as a way to let developers communicate directly with customers about product-related issues. Blogs can also be an opportunity for members of the UA team to call attention to new content and provide more detail on critical support issues.

  • Moderating or editing online discussion groups. While discussion groups have been around as long as computers, unmoderated content tends of have minimal long-term value. Curating important contributions from customers can add a lot of value to a knowledge-based with minimal effort.

  • Writing scripts for videos. YouTube-style videos are growing in popularity for software UA. However, it is more common than for video ndarration and simulations to be performed "off-the-cuff." Ideally, our videos are based on a shooting script that lays out the words and associated images.

  • Information planning or organizing for Knowledge-bases. While many organizations have a knowledge-based, it is often difficult for customers to find what they are looking. Search engine optimization and usability tests can improve the user experience with our existing content libraries.

  • Writing or editing UI text. Detailed review and editing of all the words and phrases in the software user interface can have a dramatic effect of the user experience. Often this will reduce the need for the user to launch a Help topic and in some cases eliminate the need for a topic altogether.

Most Valued User Assistance Technologies    Link to contents

The use of technologies is a defining element in the identity of software user assistance professionals. Enhancing a product's usability requires transforming our words and ideas into digital form using a variety of technologies. In our survey we provided a list of popular user assistance technologies and asked the respondents to value the importance of those technologies in their current development efforts.

The technologies we presented to the survey respondents are broad solution technologies as opposed to specific file formats. For example, Microsoft's HTML Help provides a comprehensive solution to user assistance in the Windows environment, while HTML is a technology that gains value only when used in conjunction with a broader technology like HTML Help or browser-based Help. Our work with foundation technologies like HTML, XML, and JavaScript are dealt with specifically in the Skills section of the survey.

The figure below shows the top-rated user assistance technologies. These technologies are rated as either "4" (Very Valuable) or "5" (Invaluable), the top two ratings on a five-point scale.

Most Valued User Assistance Technologies

Acrobat from Adobe has been consistently at the top of this list for many years. The ubiquitous document format is an easy choice for a variety of UA documents. With Acrobat it is extremely easy to generate the most complex PDF files in seconds. While PDF offers advanced features for linking, navigation, and interactivity, very few of us take advantage of those capabilities. PDF has essentially replaced the vast majority of printed user guides. Customers are expected to be able to download and print their own copies if needed. The close integration of Acrobat with all other Adobe products means that it is extremely easy to generate PDF from UA tools like RoboHelp and Framemaker.

The desktop browser has become the most common host for the delivery of Help content. Since browsers are available for all platforms and support standard markup, they are ideal for developing content designed to operate in multiple platforms and environments. The growth in our us of browser-based Help jumped up considerably in the mid-2000s and continues to creep upward. Authoring tools like RoboHelp provide templates to make it easy to generate browser-based content with navigational elements and context-sensitive links.

The growth of browser-based Help has been at the expense of proprietary formats like Microsoft HTML Help. A decade ago HTML Help was at the top of this chart. However, the standard has not been updated since 1998 and does not meet the needs of most UA development. That being said, two out of five of us still value it highly. The dominance of the Windows OS and Windows-based apps in desktop computing means that RoboHelp will continue to support the .chm format well into the future.

Printed documents are still valued highly by just under a third of us. While PDF is the main way to disseminate print-ready documents, there are still many organizations that need to supply paper-based content. Some organizations have legal requirements for printed books. Others have users in environments without Internet connectivity. And then there are some organizations with a user base that values having printed guides as part of the overall software solution. In all of these scenarios it is important to have documents that are well-designed for the printed page. Tools like Framemaker and RoboHelp can provide such documents, even when single-sourcing the content to other deliverables.

Multimedia tutorials have emerged as an important way to provide more visual, interactive training in support of our software. Adobe Captivate is a strong candidate for doing this type of work. The Adobe Creative Suite also offers many tools that are particularly adept at developing images. The next generation of UA tools will need to provide more support in the areas of video and audio editing.

There are also several technologies that many UA professionals are starting to include in their repertoire. The use of wikis as a content repository has increased significantly. Wikis weren't even a survey category until 2008. Now three out of ten respondents are involved with them in some respect.

One area where our Help authoring tools can definitely improve is in better integration with established content management systems. A dedicated CMS is vital to managing large-scale knowledge-bases and customer support systems.

The Platforms We Support    Link to contents

Our organizations embrace multiple platforms as a way to maximize product usage and to offset the high cost of software development. However, this results in many difficult challenges for software developers. In our part of the development process, the design and implementation of user assistance components is dictated largely by the nature and number of different platforms we need to support.

In our survey, we asked respondents to identify all of the platforms their products run on. Microsoft is still the dominant player. Almost all of the survey respondents (97%) indicated that their products support the recent versions of Windows (1), including 7, Vista, XP, and Server. Far fewer, 35%, support the older versions of Windows (2) 2000, NT, and earlier. Although the use of Microsoft's HTML Help is in decline, it continues to be an excellent solution for providing context-sensitive links between Windows applications and Help.

Platform Support

The idea of the Web as a platform is a relatively new concept. It has really been the past five years that has seen web-based applications take control of most of our personal interactions with the computer. While most large businesses still rely on Windows for mission-critical applications, the use of web-based apps has taken a strong hold in intranet and extranet configurations. What this means for UA is that browser-based Help solutions will continue to grow.

While the other platforms shown in the chart have significantly smaller percentages than Windows and the Web, it is important to keep that in context. The Mac, Linux, and other platforms easily represent over a hundred million users. The Mac in particular has experienced a lot of growth in the past five years. In our survey, one out of five of us are supporting that platform. This is likely to continue to grow with the popularity of MacBooks and the associated ecosystem of iPhones and iPads. For the Mac and Linux, web-based Help have been the primary solutions for a long time. Proprietary solutions are rarely used.

The Mobile category is a relatively new one for this survey. In just the past few years it has increased from a couple of percent to a quarter of respondents. The authoring tools of the near future will need to support outputs to formats that work well on mobile devices. Part II of this article will discuss mobile in more detail.

Part Two of this series will focus on the emerging paradigms in information technology and user assistance. This includes support for mobile devices, integration with Agile methods, convergence with training, the emergence of HTML 5, instructional video, and search engine optimization.

Joe Welinske is the president of WritersUA.

WritersUA is a company devoted to providing training and information for user assistance professionals. The WritersUA/WinWriters Conference draws hundreds of attendees each year from around the world to share the latest in user assistance design and implementation. The free content on the WritersUA web site attracts over 20,000 visitors each month. Joe has been involved with software documentation development since 1984. Joe recently published Developing User Assistance for Mobile Apps.

He has also taught online Help courses at the University of Washington, UC Santa Cruz, and Bellevue Community College. Joe received a B.S. in Industrial Engineering from the University of Illinois in 1981, and a M.S. in Adult Instructional Management from Loyola University in 1987. Joe was the President of STC Puget Sound Chapter from 2006-2008 and as Membership Director for the Puget Sound Chapter of the Usability Professionals Association in 2010.


Copyright © 2012 WritersUA. All Rights Reserved.
shannonm *at* writersua *dot* com


The Conference for Software User Assistance

'Developing User Assistance for Mobile Apps' by Joe Welinske

UI Text Design

WritersUA offers cutting-edge training and information to Technical Writers, Information Analysts and Architects, Documentation Designers, Help Authors, Publication Managers, Documentation Leads, Senior Writers and Documentation Contractors, and User Education Specialists. The focus is on software user assistance, which encompasses writing, editing, planning, coding, indexing, testing, programming, localization, and standards development.

WritersUA Home Page First Time Here Contact Us Join Our Mailing List OASIS Member RSS Resource Directory Tools Contractors Training Articles Blogs Web Resources