Active Learning for Software Products

This article shows how principles from the fields of adult learning and situated learning can be applied to the method of Instructional System Design to create classroom-based training for software products. These principles and methods do not need to be antithetical; rather, they can complement each other to create instructional strategies that incorporate context-rich activities for work-oriented instruction.
Hughes, Michael A. Technical Communication Online (1998). Academic>Computing>Instructional Design>Software
The Anatomy of a Help File: An Iterative Approach
This article presents an approach to Help file design that focuses on creating a task-centered user experience and accommodates an iterative development strategy. This methodology allows the introduction of user assistance into early test phases--not only getting earlier validation for its accuracy, but also supporting quality assurance testing by serving as the test scripts for interactions with the user interface. This approach can also be a self-contained strategy--that is, one that allows an iterative approach to user assistance development even if the rest of product development operates on a waterfall model.
Hughes, Michael A. UXmatters (2007). Articles>Documentation>Methods>Help
One of my earlier careers was in manufacturing management, and it grounded me in the principles of project planning and management. When I moved into technical communication, I brought my project management disciplines with me, and I embraced the prevailing tools of my new profession. I dutifully produced documentation plans in Microsoft Word and supported them with detailed project plans in Microsoft Project. However, the problem is that—like bad relationships—these artifacts never gave back results that were sufficient to reward the effort I put into creating them.
Hughes, Michael A. UXmatters (2008). Articles>Documentation>Technical Writing>Microsoft Excel
The Help Landscape: A Mile Wide and 30 Seconds Deep
Two questions any writer must deal with are: 'What do I write about?' and 'How much do I say about it?' Essentially, these questions deal with the scope and the depth of a document. Technical communicators have a tendency to want to document a topic as completely as possible, and we carry this instinct with us when we architect and write Help files. In this column, I challenge that prevalent instinct and offer an alternative way of thinking about the scope and depth requirements of Help systems. The benefits of this approach are, I hope, better Help for users and, for our clients and employers, a more efficient use of technical communicators' time. First, I'll discuss three principles that underpin my perspective, then I'll give some practical advice about writing Help that people will actually use.
Hughes, Michael A. UXmatters (2007). Articles>Documentation>Help>Online
Hockey Sticks and User Assistance: Writing in Times of Resource Constraints
If you have all the resources you need, do the very best job you can in all respects. But if your resources are tight, ask yourself whether you are writing the essential stuff at a level of quality users will notice. Also, ask whether the value of the documentation you are producing aligns with the economic pressures on your company.
Hughes, Michael A. UXmatters (2008). Articles>Writing>Technical Editing
Instructional Text in the User Interface: Some Counterintuitive Implications of User Behaviors
User assistance occurs within an action context--the user doing something with an application--and should appear in close proximity to the focus of that action--that is, the application it supports. The optimal placement of user assistance, space permitting, is in the user interface itself. We typically call that kind of user assistance instructional text. But when placing user assistance within an application as instructional text, we must modify conventional principles of good information design to accommodate certain forces within an interactive user interface. This column, User Assistance, talks about how the rules for effective instruction change when creating instructional text for display within the context of a user interface.
Hughes, Michael A. UXmatters (2007). Articles>User Interface>Help>Online
Managers: Move from Silos to Channels 
Advocates restructuring technical communication departments to eliminate 'silos'—isolated groups within the department—and develop 'channels'—a cooperative grouping of workers and teams through which information about a product can flow.
Hughes, Michael A. Intercom (2003). Careers>Management>Collaboration
Moving from Information Mapping to DITA

Is your company making the move from Information Mapping to DITA (Darwin Information Typing Architecture)? The author compares and contrasts the two methods and shares insight on how to ease the pain of switching from one to the other.
Hughes, Michael A. Intercom (2008). Articles>Information Design>XML>DITA
This article first reviews the current literature that addresses the value of the technical communicator. Whereas those discussions focus on what is delivered to the user (reader), this article examines the value the technical communicator adds by creating organization (internal) knowledge. The article then examines the philosophical underpinnings that support any discussion of knowledge and defines the role of technical communicators as creators of knowledge. Finally, it offers an expanded value proposition for technical communicators and examines its practical implications.
Hughes, Michael A. Technical Communication Online (2002). Articles>TC>Assessment
This article first reviews the current literature that addresses the value of the technical communicator. Whereas those discussions focus on what is delivered to the user (reader), this article examines the value the technical communicator adds by creating organization (internal) knowledge. The article then examines the philosophical underpinnings that support any discussion of knowledge and defines the role of technical communicators as creators of knowledge. Finally, it offers an expanded value proposition for technical communicators and examines its practical implications.
Hughes, Michael A. Technical Communication Online (2002). Design>Information Design>Content Management>SMEs
Companies can improve customer satisfaction while reducing training time and product support costs by integrating online documentation with product training. Online documentation can be designed to be not only the reference at the point of use but also the primary instructional medium used during training. This use of the online documentation during training increases user acceptance of it and helps develop the required skills for its use. This expanded role for online documentation provides new opportunities for technical communicators to add value to their roles within their companies. This article defines reference-based instruction and outlines its benefits. It describes how reference-based instruction can be incorporated into an instructional system design (ISD) and provides specific examples of learning objectives and student exercises. It lists guidelines for how to structure usability tests for Help systems, and finally, it advises how technical communicators can use reference-based instruction to ex
Hughes, Michael A. Technical Communication Online (1997). Articles>Documentation>Instructional Design>Education
A Pattern Language Approach to Usability Knowledge Management

Knowledge gained from usability testing is often applied merely to the immediate product under test and then forgotten--at least at an organizational level. This article describes a usability knowledge management system (KMS) based on principles of pattern language and use-case writing that offers a way to turn lessons learned from usability testing into organizational knowledge that can be leveraged across different projects and different design teams.
Hughes, Michael A. Journal of Usability Studies (2006). Articles>Usability>Knowledge Management>Language
Procedures: The Sacred Cow Blocking the Road? 
This paper questions the dominance of procedures in paper and online computer documentation and argues that the types of behavior and conditions demanded by stepped instructions are not consistent with typical user behavior. The authors suggest that the following hierarchy of information needs more accurately describes what users want to know when they ask, “How do I:” (a) What can I do? (b) Where can I do it? (c) What are the rules or principles? (d) What are the parts and their functions of the interface that does it? and (e) What are the steps?
Hughes, Michael A. and Loren Burke. STC Proceedings (1998). Articles>Documentation>Policies and Procedures
Usability testing is an evaluation method used by technical communicators that can combine aspects of both quantitative and qualitative research methodologies. This article compares and contrasts the standards and techniques between these two methods of inquiry with particular emphasis on maintaining rigorous tests in regard to validity and reliability of the findings. Whether an evaluator relies on quantitative methods, qualitative methods, or both, should depend on the questions the research or evaluation seeks to answer. Both methods have well-established practices meant to ensure the validity and reliability of their findings. Not only should usability evaluators be competent within the method of inquiry they apply, they also need to help clients understand the legitimate application and limitations of their findings.
Hughes, Michael A. Technical Communication Online (1999). Articles>Usability>Testing>Methods
Review: The STC 54th Annual Conference
What I saw was a society of professionals emerging from a process of reflection and redefinition with a vitality and momentum that said, "There's a new sheriff in town, and she's brought the posse with her." The sheriff is Susan Burton, the new STC Director.
Hughes, Michael A. UXmatters (2007). Articles>Reviews>Knowledge Management
A Tech Writer Dies and Goes to Heaven
A joke about what technical writers' heaven might be like.
Hughes, Michael A. Blogspot (2008). Humor>Writing>Technical Writing>SMEs
User Assistance in the Role of Domain Expert
This article explores the role of user assistance in providing domain-centric online Help--rather than Help that simply explains obvious user interactions with well-designed user interfaces--and provides a pattern for and examples of expert guidance.
Hughes, Michael A. UXmatters (2007). Articles>User Centered Design>Help>Online
User Assistance Walkthroughs: Helping Best Practices Emerge
In my previous job as a UX designer, I learned the value of collaborative design walkthroughs. During walkthroughs, the UX designer would step through a user scenario--using the wireframes or mid-fidelity prototypes--with a cross-disciplinary team comprising product management, other UX designers, business analysts, developers, product testers, and technical communicators.
Hughes, Michael A. UXmatters (2007). Careers>Consulting>Design
User Assistance: Writing for a High-Context Culture
What we consider to be good technical writing often reflects an American cultural perspective. One facet of this cultural orientation is that technical writing tends to use a low-context style. Most notably, we tend to write user assistance as if users have never seen the user interface we are explaining. Secondly, we tend to write user assistance as if users have never even used software before. But users rarely go to Help before they have tried to accomplish a task on their own first, and most users today have extensive experience using software and are familiar with the standard ways of interacting with user interfaces. So a user interface is a high-context artifact—one a user has already seen before reading our documentation and that uses rules and conventions the user already knows.
Hughes, Michael A. UXmatters (2008). Articles>Documentation>Help>Technical Writing
I hate user manuals that are distributed as PDFs. They are mainly used online so why the artificial page constraints? I'm in the middle of a topic and all of a sudden there is a page break--not because of a topical shift but because had it been printed on 8.5 x 11 we would have run out of paper. News flash: I didn't print it and I was not running out of paper.
Hughes, Michael A. User Assistance (2008). Articles>Documentation>User Experience>Adobe Acrobat
I've long been an advocate that teaching technical communication without teaching tools is like teaching art students about painting without talking about brushes.
Hughes, Michael A. User Assistance (2008). Articles>TC>Software
The Sixty-Minute Guide to Evaluating Comparative Test Data
Mary wants to compare the average registration times between the two versions to see if the second version is faster than the first. The method typically used when comparing averages is called a t-test of independent means.
Hughes, Michael A. STC Proceedings (2008). Articles>Usability>Testing>Assessment
Use Cases for User Assistance Writers
It’s hard to find anyone who disparages use cases, but those who use them are still a minority. In a previous life as a UX designer, I used use cases and developed a great respect for them. But it wasn’t until recently that I began using them to design user assistance. Why did it take me so long to get back to these reliable work horses of user-centered design?
Hughes, Michael A. UXmatters (2008). Articles>User Centered Design>Writing>Technical Writing
Placing Value on User Assistance
User assistance writers are often the Rodney Dangerfields of the UX world, bemoaning the fact that we don’t get any respect. I think the real problem is that user assistance folks are not particularly good at communicating the ways in which we add value to an enterprise. This column explores two models that show how user assistance adds value and how we can communicate that value to those who pay our salaries—something I would like to encourage other user assistance writers to do.
Hughes, Michael A. UXmatters (2008). Articles>Documentation>Technical Writing>Help
PDF Manuals: The Wrong Paradigm for an Online Experience
Let me describe a familiar user assistance experience. A user installs a new application, and when the user wants Help, the application directs her to the user documentation on a Web site or CD-ROM. What the user finds there is a PDF file containing the manual—or a collection of PDF files, representing a library of manuals, including a user guide, configuration guide, troubleshooting guide, and various references. And the layout of each of these PDF manuals is exactly the same as if it were a printed book. This raises an interesting question: If we’re giving manuals to users to read online, why do we design and write them for paper?
Hughes, Michael A. UXmatters (2008). Articles>Documentation>User Experience>Adobe Acrobat
There are 13 readers currently online: 1 registered user and 12 guests. Register.

![]()
![]()


![]()
![]()
![]()