Trends and Opportunities in Software User Assistance – Part 1

By Joe Welinske

The birth of the new year, 2005, brings us a 50^th anniversary of sorts. The mid-1950s marked the beginning of widespread sales of computers for commercial purposes. ENIAC, ILIAC, and other pioneering machines had been in use since the 1940s for the purpose of weapons targeting and code-breaking. But 1954-55 brought forth mature versions of the UNIVAC and IBM 700 series computers which were quickly snapped up by large corporations. Around that same time, John Backus developed FORTRAN for IBM. This was the first high level programming language and it helped launch the first wave of software (not yet called that) developed for commercial purposes. This period also saw the emergence of technical writing as a professional discipline in its own right including the founding of The Society of Technical Writers, the Technical Publishing Society, the Association of Technical Writers and Editors, and the Technical Communicators Association.

The word "software" appeared circa 1960 to account for the proliferation of application programming code that accompanied the computer. Application development was generally controlled by a small core of programmers. The programmers rarely, if ever, interacted with end users, and users rarely had access to the programmers. The earliest computing systems from IBM and Sperry-Rand each came with their own support team. As buyers began to take control of their own day-to-day support, it was necessary for computer manufacturers to provide the essential printed documentation. Software user assistance had come into being, but it would be another forty years before anyone would call it that.

Throughout the 1960s and 70s, software documentation was centered around support for "hard iron" – corporate and institutional applications running on mainframe computers. In this era of paper-based manuals, documentation was often valued by the net weight of the stack of manuals. Professor David Farkas of the University of Washington remembers the arrival of a Xerox Star computer system that had so many manuals it came with its own bookshelf! Despite all of the gains in software design, the need for users to become familiar with complex systems still requires a bit of help. That's where software user assistance comes into play. User assistance is the link between what an application can do and what users want/need to understand about it.

What Do User Assistance Professionals Do?

The term "user assistance" reflects the growth of this discipline beyond printed manuals and proprietary "Help" content viewers. Today, the field of software user assistance encompasses a wide range of skills and technologies. We contribute through wizards, tutorials, and web-based training. We develop and populate knowledge bases and content management systems. Many of us are now embedding helpful content directly into the user interface. We are involved with usability testing, localization, quality assurance, and branding. Printed manuals, and their PDF equivalents, are still an important element of our documentation sets. The types of applications user assistance professionals support are spread across a wide spectrum of utility – the software might be a shrink-wrapped word processor or a proprietary corporate accounting system or a web-based shopping site. The users we support could be our fellow employees, purchasers of our product, or a shopper on the Web.

The depth and breadth of user assistance is impossible to sum up with a buzzword or trendy phrase. A better way is to take a brief look at some of the innovative ways that our colleagues are supporting users today.

• A Dynamic Documentation Checklist
  BMC Software, Inc., sells bundles of products to customers for use in its business applications. Previously, BMC provided its customers with a large bundle of hardcopy checklists. If customers were installing more than one product, they would have to look through the bundle of checklists, find the checklists appropriate to their products, and try to manually merge the steps from each checklist as each produce was installed. Improving on this, the documentation team developed the Installation Checklist Generator (ICG). As Margaret Yen, one of the team leaders, explains, "Individual writers maintain a FrameMaker file with their product's installation information and save it as HTML. These HTML files are collected by the ICG and written into a flat data repository. Now the customer simply accesses the ICG, selects the designed products, and the ICG produces a dynamic HTML checklist tailored specifically to the selected product set."
  
• Single-source Content Delivered by Active Server Pages
  At the USDA Forest Service, as at many corporations today, content development resources are a scarce commodity. Single-sourcing techniques and author-written Active Server Page (ASP) scripts have now been implemented to streamline the process. The documentation team produces all their online reference manuals from two sources: database reference pages from Oracle-generated XML and forms reference pages from FrameMaker-generated HTML. Both kinds of data are processed by the ASP scripts and formatted into web-ready HTML that then goes into RoboHelp where WebHelp files are generated and published to the documentation server. The user simply presses F1 to obtain context-sensitive Help text for the active form, positioned to the field that has focus.
• A Custom Solution for the Delivery of Field-level Help
  One of the never-ending issues associated with online Help text is finding enough screen real estate to present the necessary information. Conversely, too much information creates noise and actually gets in the way of the learning process. A solution used at Advantica is an expandable field-level help viewer, which is embedded in the dialog boxes of Advantica applications. The help viewer provides a context-sensitive description for any control that is selected in the dialog box. The field-level help topics are written directly in the main help files, which are created in structured FrameMaker 7.0. These field-level help descriptions are then extracted to a separate FrameMaker file using a custom-developed API procedure. Both the main help file and the field-level help topics are compiled into a single CHM file using WebWorks Publisher. The field-level help topics are hidden from the main CHM file, so that they can only be seen in the application.
• An Answer Station Web Site
  The documentation team at Rockwell had been considering using the Web as a platform for providing updated documentation to users. But the thought was, "Why stop there?" Documentation can help make users successful quickly, but often other resources are available to assist them. According to one of the team members Nicky Bleiel, "With the Answer Station web site that is accessible from the application, we could not only direct users to updated documentation, but we can also guide users to technical support, consulting, training, sales, and other useful information." This venture required a lot of design work, including assessing the need for an Answer Station, presenting a business case for it, using brainstorming and detective work to determine what users needed, and finally delivering the solution to the users.
• Flow Diagrams as System Overviews and Navigational Tools
  OMD Vision is a business software solution that enables users to perform more than 1500 business application functions on Windows, Unix, and Linux platforms. Within this complex system, users need to find specific information associated with their workflow process. To this end, Tim Morris and the user assistance team include hyper-linked workflow diagrams within the primary Table of Contents (TOC) books. They create flow diagrams in SmartDraw, modify them in PhotoShop, and associate image maps with the diagrams in RoboHelp. Then they link flow diagram text to applicable help topics that explain program functionality and provide step-by-step setup and processing procedures. Flow diagram icons (not page icons) identify flow diagrams in the TOC, and a WinBatch script automatically updates these icons.

Whew! That's a lot of very involved stuff. Not bad for a bunch of tech writers. These kinds of stories can be found throughout the software industry. Pundits who decry the current state of user assistance are obviously not spending enough time in the field. There's a lot of cool stuff happening out there.

The People Who Work in Software User Assistance

The most unifying attribute of user assistance professionals is an interest in employing language to clarify the methods associated with the software we are charged to support. While we may use a variety of media and underlying technology to deliver our message, it's the message that ultimately provides value to the user. Taxonomies and navigation panes and popup bubbles help to frame the content, but it's the words that conduct the communication. Clear, concise prose has always trumped glossy presentation.

Most user assistance practitioners can relate to the difficult experience of trying to explain what we do to our friends and family. In response we often hear people say, "Help never Helps" or "So you get paid to write that crap?" One of the unfortunate realities of software documentation development is that the large majority of it appears to be done by people who would much rather be spending their time doing something else. Usability guru Jakob Nielsen has said, "People are ruthless at concluding things are useless because they are so conditioned by useless stuff." The use of a trained documentation professional is still the exception rather than the rule in most software development efforts. Those of us who embrace user assistance as a profession have to resign ourselves to the fact that our good works will always be outnumbered by the "useless stuff." That being said, those of us who do treat this as a craft find the work challenging and rewarding.

And there are a lot of us involved with this craft. The U.S. Bureau of Labor Statistics counts 50,000 people officially employed as technical writers in the U.S. The Employment Trends Survey in the January 2004 issue of STC Intercom reported that over 50% of respondents service the software industry. That equates to around 10,000 members in the ranks of STC alone. The WritersUA active contact list is just over 10,000 people worldwide.

Unfortunately, the disastrous bursting of the Internet bubble and a humbling, long economic recovery has taken an immense toll on our field. WritersUA estimates that one-third of its customers have been forced out of the user assistance field due to the lack of jobs. A recent survey from the University of Illinois-Chicago found that over 400,000 jobs have been lost in the IT field in the past three years. Since 2001, over half of the IT job holders in the San Francisco Bay Area have lost their positions.

The current economic situation has resulted in a fragmentation of the valuation of our role as user assistance professionals. Organizations like Microsoft, Intuit, Oracle, Sun, and Hewlett Packard continue to employ and deploy large numbers of trained user assistance professionals to support their products. For these and other organizations, cash flow is sufficient to maintain their development values during a period of decreased revenue. However, many other companies have struggled to meet payroll through these desperate times and decisions have been made to reduce the number of employees. This has affected people with many different roles, not just in user assistance.

The Foundation Skills of Software User Assistance

Traditional aspects of technical communication remain the foundation of user assistance. Employers expect that we already have high-level skills in writing and editing before we come knocking for a job. The 2004 STC Salary Survey showed that 83% of respondents chose "Writing" as "Very Important," making it the highest vote-getting skill. In the WritersUA Skills and Technology Survey, 89% of respondents rated the "Writing of Procedures" as "Very Valuable" or "Invaluable". This was the top ranked skill.

Sometimes it is difficult for us to articulate the value of what we do to our bosses and colleagues. They think, "For a procedure, all you have to do is write three or our sentences. Takes maybe ten minutes tops, right?" Well, you might be able to string together a few dozen words during a coffee break, but that doesn't get you much. Let's take a look at an example procedure from an actual web-based application. The topic is about how to change the email address that you have previously registered with this application. Read the passage below and make note of the various issues that an experienced writer might have addressed.

Changing Your Email Address
Please visit our website (www.url.com) and choose "My Account" or "Log in" (located on the left hand side of the web page screen) and enter your PIN number. Once you have logged into your account, you may change your email address in the main profile. After making change to your account profile, make sure that you save the changes by clicking on the "Save Changes" button at the bottom of the screen.

Now let's review some of the issues.

• In the first sentence, the writer starts the procedure by telling the user to go to the company web site. Since this is a web-based application, users would not even be seeing these instructions unless they were already online and viewing that web site. This text was clearly lifted from some marketing materials.
• Note that the procedure doesn't actually tell you how to access the main profile or how to change it. The assumption is made (wrongly, in this case) that once you are on the correct page it is obvious what to do.
• Grammar is always important. The improper verb tense for "change" in the third sentence is unacceptable in a business situation.
• Finally, it would be helpful to break the extended prose paragraph into more digestable chunks. We call them steps.

There are other issues with this passage that are not apparent just from reading the text. In the second sentence, the procedure references a "main" profile. But it turns out that it's only possible to have one profile. That adjective would waste the user's time if he or she tried to find out how to have an alternate profile. And notice in the last sentence the reference to the button at the "bottom of the screen." What they actually meant was that it is at the bottom of the web page. Depending on the type of browser, display resolution, and screen size, that button may not be visible at all. You would have to scroll down to find it.

Much of the above might seem like nitpicking to the casual observer. The procedure as shown is good enough, right? No, wrong! The issues described are exactly the types of things that make Help not helpful and condition people to be wary of "useless stuff." More importantly, these picked nits are not at all difficult for an experienced writer to anticipate and avoid or to identify and correct. User assistance professionals are trained to evaluate many layers of the implicit dialog we carry on with our users. We know that to develop a correct, effective, and usable procedure, the writer needs the skills to go a lot deeper than just writing sentences.

Editing is another foundation skill that can be employed at several levels. Most organizations expect all of us to be familiar already with the basic techniques of copy editing and proofreading. Grammar errors are never acceptable, no matter what the budget is for the work. Nothing shouts "I don't care" louder than misspelled words and mismatched verb tenses.

There are also higher levels of editing that can pay big dividends. A good developmental editor can help a team of writers create a well-organized message with a unified voice. Technical editing ensures that the information is accurate and reflects the current state of the software. These skills are often learned on the job–ideally through a mentoring relationship. Writers with strong editing skills are often the ones best able to hang on to a job in difficult times.

A few prominent figures in the field of technical communication have raised the alarm that being "just a writer" can be a career stopper; that specializing in technical wordsmithing make one anachronistic and a liability to the profession. Their reasoning is that information is now so complex that its architecture is where the big-time jobs are. Unfortunately, that shows a misunderstanding of our profession on two levels. One, there is always going to have to be someone to produce the words. You can spend as much time as you like building taxonomies and designing schemas, but eventually someone needs to take finger to key and create some readable prose. The second reason these pundits are mistaken is that their desire for corporate recognition ignores the love so many of us have for writing. It is wrong to suggest that people whose main interest is in technical writing need to become information scientists or semantic theorists, if what gives them satisfaction is flowing words together. If you're a veterinarian, or a florist, or writer, then that is who you are and you shouldn't have to apologize for it.

Building on the Foundation Skills

The foundation skills of writing and editing need to be on your resume just to be considered for a job. However, there are many other skills built upon that foundation that you need in order to win the position. Task analysis, interviewing, usability testing, and indexing should all be part of your user assistance repertoire. These skills are found in the curricula of many university technical communication programs. You can also acquire these through seminars and in the field.

Task analysis is arguably second in importance only to writing. A well-crafted procedure is the culmination of a careful analysis of both the user and the application. We identify objectives, evaluate learning styles, explore the application, and then craft the instruction. A task analysis is the soul of a procedure. A thorough task analysis for user assistance purposes also serves as a vetting of the application itself. Putting a task to words often illuminates problems with the user interface.

Interviewing subject matter experts is also at the heart of our work. It would be difficult for any of us to know all the inner workings of a piece of software. Even if we were able to keep up with all of the features ourselves, we may not always understand the business processes associated with them. Knowing how to stage an interview with an expert and extract the required information is something that should be an important part of everyone's skill set.

Usability testing has become a major area of development in its own right. Most major software companies employ specialists trained in evaluating the effectiveness of application design. For user assistance professionals, it's a way to test our components to make sure they have the desired effect. A full-scale usability lab is not required to have an impact on our work. That's fortunate, because too few budget dollars tend to be allocated to user assistance testing. However, many researchers have discussed card sorting and other paper-based techniques for evaluating the effect of a documentation design before the writing and coding begins in earnest.

Indexing borders on an art form when it is most effective. Yet, most documentation sets these days do not even feature an index. An index isn't technically difficult to create, but it is highly time-consuming to develop the entries. Humans still seem to be the preferred engine in developing a good index. Some of the best keywords used to build a good index appear through our interactions with users and customer service representatives. According to indexing specialist Jan Wright, "Indexing and taxonomy work require looking at your material from a cross-hatched point of view, as well as understanding an audience and understanding finding behavior. The content analysis means taking your brain out and putting it in sideways."

The "software" in software user assistance means that we are part of the digital domain. Technical tasks that were unknown to our tech writing forebears of just 20 years ago are now part of our daily lives. The specialization of working within the software industry is not trivial. Software development requires the ability to deal with aggressive schedules, swiftly evolving technologies, and high-profile design decisions. Very few passive, slow moving software companies exist today. Being involved in the development process of a software project can often feel like performing a high wire act on a moving train.

Testing, Quality Assurance, Validation, and Localization have become important aspects of our work. These skills bridge the gap between the pure and the applied. They are work areas that are common to virtually every team in the application development process. Generally, the specific processes and techniques used are unique to individual organizations. The basics of Quality Assurance may be the same in many organizations, but others will have a completely different way to define it. These are skills best learned on the job.

Conclusion

It is very difficult to exhaust the list of things we do. There are numerous activities of peripheral interest to user assistance. The field of instructional design can play a strong role in improving the development of tutorials and wizards. An understanding of graphics rendering is important as you work with screen shots, icons, flow diagrams, and other conceptual art. Even branding issues have entered our domain.

The most important note to carry away from this article is that our core mission to support the user through language moves beyond the words and manifests itself in numerous related disciplines. There's a lot to learn and the learning never stops.

Part Two of this article will appear in January. The focus will be on the importance of development platforms and the various technologies that are relevant to software user assistance.

Joe Welinske is the president of WritersUA, formerly known as WinWriters. WritersUA is a company devoted to providing training and information for user assistance professionals. Joe has been involved with software documentation development since 1984. Together with Scott Boggan and David Farkas, Joe authored two editions of the popular and pioneering book Developing Online Help for Windows. He has also taught online Help courses at the University of Washington and UC Santa Cruz. 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.