http://tc.eserver.org/authors/Hughes,_Michael_A. A bibliography of works by Hughes, Michael A. in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Hughes,_Michael_A. http://tc.eserver.org/35757.html http://tc.eserver.org/35757.html STC SIGs are like areas where outside professions insert specialized instances of their expertise into our profession. But what if we could reverse that gateway? Our SIGs could be an excellent outreach channel to market our specialized knowledge into those other professions. http://tc.eserver.org/35758.html http://tc.eserver.org/35758.html We go from one moment being very proficient with our current tool or technology to being pretty stupid with a new one. So the basic question every user ends up answering is Was the improvement labeled "B" worth the pain and humiliation labeled "A?" http://tc.eserver.org/35645.html http://tc.eserver.org/35645.html Many of us are more comfortable communicating in words than in pictures. For example, user assistance writers are by nature and training writers, so they understand words and are adept at using word processing and publishing tools. Writers use lexicentric tools not only for creating and delivering content, but also as cognitive tools—that is, tools that help them think more clearly and efficiently. Thus, a user assistance writer might create a user-task matrix or take advantage of a word processor’s outline view when creating or evaluating a document’s structure. http://tc.eserver.org/35572.html http://tc.eserver.org/35572.html As part of a project I'm working on, we are going to develop a comic-style collection of user scenarios to help communicate best practices around a security service we are offering. http://tc.eserver.org/35369.html http://tc.eserver.org/35369.html We confuse people when there is a disconnect between our stated beliefs and our theories in use. When managers say they demand teamwork but evaluate employees based on individual accomplishments, they do a disservice to the person who puts the team's overall needs ahead of his or her specific goals. That person gets punished for believing what the boss said and acting on it. But don't be so quick to blame the disconnect on your behavior--It could be you are reciting scripts that describe what you think you should do. http://tc.eserver.org/35303.html http://tc.eserver.org/35303.html Just as I would with words, I'll cut out the obvious and whatever does not add value. I prefer an additive approach (put it in only when the words seem inadequate) over a subtractive approach (take it out if it seems superfluous). In other words, I'll be more open to screen shots in the future, but they have to work themselves into the document, not just be their by entitlement until expelled. http://tc.eserver.org/35225.html http://tc.eserver.org/35225.html Perhaps the true measure of a good idea is its persistence, even though folks are slow to pick up on it. SGML is a good example. It seemed like a great idea, but for a long time, had trouble getting traction in the general tool space. Then it started showing up at technical communication conferences wearing a name badge that said, “Hi, my name is DITA,” and suddenly, it’s a hit! http://tc.eserver.org/35186.html http://tc.eserver.org/35186.html I need to figure out where I am with all the STC stuff going on, and blogging will help my introspection. Also, it will let me share with you some of the background and complexity that surround the current state of affairs with STC. My e-mail tag line reads "Anyone who is sure of the answer doesn't understand the question," and this blog is an invitation to join me in understanding how we got here, where we are, and where I think we need to go. http://tc.eserver.org/34867.html http://tc.eserver.org/34867.html Pay attention to the legal requirements and translatability issues, not only in your own documents, but in the documents of other groups like marketing and engineering. It's an area where we add value. http://tc.eserver.org/34709.html http://tc.eserver.org/34709.html This isn't a discussion of hyphenated vs. not hyphenated. It examines the difference between putting a PDF file on the Internet (what I call an on-line document) and having a truly electronic Web presence for that content (what I call an online document). Unfortunately, the two often get bundled together. http://tc.eserver.org/34468.html http://tc.eserver.org/34468.html In this column, I’ll review what user assistance architects mean by reuse and what its benefits can be. I’ll then describe some different scenarios for reuse and offer guidelines that user assistance architects and information developers can follow. My examples show how DITA (Darwin Information Typing Architecture) can be an effective reuse framework. But the principles I discuss go beyond DITA, and you can apply them to any structured information framework or toolset. http://tc.eserver.org/34446.html http://tc.eserver.org/34446.html A colleague has made me realize that user assistance writers are codependents of bad UI design. Because we explain how the UI really works, we somehow leave our developers and companies feeling like they're "covered" when the users have a bad experience. http://tc.eserver.org/34093.html http://tc.eserver.org/34093.html User assistance can add value to a product or Web service’s business model by influencing how deeply users adopt new features or services. As more products employ pay-as-you-go models like that of SaaS (Software as a Service), the contribution user assistance makes becomes increasingly more important. http://tc.eserver.org/33690.html http://tc.eserver.org/33690.html Early in my technical communication management career—more than twenty years ago—I made this observation: “I can produce a manual that users won’t read for $50,000, or I can produce a manual that users won’t read for $5,000.” My point was that, until we started writing manuals users actually read, the $5,000 option was the better business strategy. But now, to heck with producing manuals users won’t read. This new world of post-2008 meltdown has changed the game. We must now write manuals users will read, and we must write them for $5,000. http://tc.eserver.org/33601.html http://tc.eserver.org/33601.html Help is read in snippets. Avoid ambiguous parts of speech and make each snippet a good little play that you can easily imagine being acted out on stage. http://tc.eserver.org/33476.html http://tc.eserver.org/33476.html When product teams ask technical writers to document software products, writers usually start their projects by analyzing the tasks users will perform when working with them. A task analysis generates a list of procedures—plus the supporting information users need to follow them—and eventually results in a document in which sequentially numbered instructions are the dominant type of information—neatly organized under user-centered task headings and preceded by enabling knowledge. It sounds ideal, classical even. The problem? Users don’t read procedures. http://tc.eserver.org/33477.html http://tc.eserver.org/33477.html 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. http://tc.eserver.org/33372.html http://tc.eserver.org/33372.html I am ill equipped to write for an emerging segment of the marketplace. But that doesn't mean I'm used up like a worn-out number two pencil stub (my favorite simile these days). But it does mean that I need to reevaluate where and how I add value. http://tc.eserver.org/33154.html http://tc.eserver.org/33154.html 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? http://tc.eserver.org/32776.html http://tc.eserver.org/32776.html 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. http://tc.eserver.org/32590.html http://tc.eserver.org/32590.html 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? http://tc.eserver.org/32546.html http://tc.eserver.org/32546.html 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. http://tc.eserver.org/32088.html http://tc.eserver.org/32088.html I've long been an advocate that teaching technical communication without teaching tools is like teaching art students about painting without talking about brushes. http://tc.eserver.org/32039.html http://tc.eserver.org/32039.html 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. http://tc.eserver.org/31889.html http://tc.eserver.org/31889.html A joke about what technical writers' heaven might be like. http://tc.eserver.org/31870.html http://tc.eserver.org/31870.html 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. http://tc.eserver.org/31597.html http://tc.eserver.org/31597.html 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. http://tc.eserver.org/31357.html http://tc.eserver.org/31357.html 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. http://tc.eserver.org/30818.html http://tc.eserver.org/30818.html 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. http://tc.eserver.org/29926.html http://tc.eserver.org/29926.html 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. http://tc.eserver.org/29289.html http://tc.eserver.org/29289.html 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. http://tc.eserver.org/28905.html http://tc.eserver.org/28905.html 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. http://tc.eserver.org/28900.html http://tc.eserver.org/28900.html 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. http://tc.eserver.org/28658.html http://tc.eserver.org/28658.html 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. http://tc.eserver.org/28665.html http://tc.eserver.org/28665.html 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. http://tc.eserver.org/28019.html http://tc.eserver.org/28019.html 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. http://tc.eserver.org/24332.html http://tc.eserver.org/24332.html 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? http://tc.eserver.org/18534.html http://tc.eserver.org/18534.html 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. http://tc.eserver.org/14255.html http://tc.eserver.org/14255.html 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. http://tc.eserver.org/13602.html http://tc.eserver.org/13602.html 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. http://tc.eserver.org/10383.html http://tc.eserver.org/10383.html 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. http://tc.eserver.org/10354.html http://tc.eserver.org/10354.html 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. http://tc.eserver.org/10319.html http://tc.eserver.org/10319.html 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