Adding User Annotations to Help Topics

This article discusses a feature called User Annotations, whereby users can add their own custom notes to Help topics, and presents a method for implementing it in web pages or in HTML Help topics.

Gash, Dave. WritersUA (2002). Design>Documentation

Constructing a One-Stop "Answer Station" Website for Software Users

The web allows us to easily provide updated documentation to our users, but why stop there? There is more to making users successful quickly than just providing documentation. By creating a complete 'Answer Station' that is accessible from the application or product, we can not only direct users to that updated documentation, but we can also provide information about technical support, consulting, training, sales, etc. This article discusses writing a proposal for an Answer Station, determining content, working with other departments to gather information, designing the site, making that design work with an existing corporate website, dealing with tool issues, and finally, going live.

Bleiel, Nicoletta A. and Beth A. Williams. WritersUA (2004). Articles>Documentation>Web Design>Help

Creating "Smart Help" with Conditional Content

Discusses several methods for making Web-based Help systems 'smart,' by using conditional content to customize the appearance and behavior of your pages to the users' needs.

Gash, Dave. WritersUA (2005). Articles>Documentation>Help>Adaptive

Design Checklists for Online Help

Online help systems have evolved over the past 20 years to meet the needs of our users. Designers must consider the content, format, presentation, navigation, and access methods of online help systems. A series of design checklists based on the past 20 years of research are presented in this paper, which summarizes a journal article currently being considered for publication. The latest trend in online help system design is embedded user assistance, which includes integrating information into the interface and including an embedded help pane within that interface to display a context-sensitive online help system.

Corbin Nichols, Michelle. WritersUA (2004). Articles>Documentation>Help>Online

Designing and Writing to Reduce User Errors

A vast majority of documents (I consider print and online as documentation) often works to define the optimized error-free method of performing a task and provides a user with a straightforward solution. However, the user expects documentation to help solve problems and address errors. Thus, attention must be paid to potential problems users can have and how to correct them. Errors have different causes; the information designer should understand the potential types of errors since properly addressing each type requires a different approach in the design and documentation.

Albers, Michael J. WritersUA (2004). Articles>Writing>Technical Writing>Usability

Determining When to Use Show-Me Helps and Demos

The availability of powerful yet easy-to-use multimedia tools enables technical writers to consider a powerful new form of embedded user assistance: show-me help. This paper provides an overview of who is currently using show-me help--some current research, some history, and some definitions. It offers some guidance in choosing tools, designing show-me help, and deciding when to include then, concentrating on consideration of your users, potential topics, subsequent releases, and translation. It also suggests how show-me helps can be reused as part of product education and single-sourced into user assistance from the Web.

Bradford, Annette Norris. WritersUA (2005). Articles>Documentation>Multimedia>Video

FrameMaker: Structured or Unstructured?

At the 2004 WritersUA and STC Conferences, structured FrameMaker and XML were among the more popular session topics. There is obviously significant interest in the user assistance community about authoring XML documents with structured FrameMaker. This is not surprising, as many organizations are struggling with the problems of creating and delivering increasing amounts of user assistance in multiple formats, and managing their content in a way that maximizes their capabilities to reuse content across multiple publications.

Houser, Alan R. WritersUA (2004). Articles>Document Design>Software>Adobe FrameMaker

The Future of Indexing?

A recent article in the Society for Technical Communications' Intercom magazine proclaimed that indexing is on the rise (Seth Maislin, "The Indexing Revival," February, 2005), and that there is a renaissance of work in the field. But at the WritersUA March Conference, Microsoft's Longhorn features session declared that Longhorn's Help system will not contain an index, because "no one uses it." Then, to add to the discussion, at that same conference Apple revealed that their next help engine will include synonym rings and will add a form of indexing back into their display. Who's right? Who's correctly predicting the trends?

Wright, Jan C. WritersUA (2004). Articles>Indexing

The Future of RoboHelp?

The RoboHelp help authoring tool is now entering its thirteenth year of existence. That's a remarkably long existence for any software title. In that time period, we have seen an amazing expansion of the software industry throughout the 1990s and an equally amazing retraction due to the bursting of the Internet bubble. Making its start in the tiny offices of Blue Sky Software in LaJolla, California, RoboHelp grew into an extremely profitable product. It is also a market leader—having capturing some two-thirds of all Help authoring tool sales. During the Internet bubble years the company changed its name to eHelp, but RoboHelp continued to be its flagship profit center. In 2003, eHelp (and RoboHelp) were acquired by one of the leading providers of web tools—Macromedia. Now it appears that the end may be approaching for RoboHelp.

Welinske, Joe. WritersUA (2005). Articles>Documentation>Software>RoboHelp

Integrating Partner Information Using XML and XSL

Having learned that two of these database companies already used single-source files for their error messages, BMC Software integrated the information about the error messages from the database companies. We accomplished our goal by negotiating with our partner companies for the source files of the error message information. This session discusses how we took those source files and modified them to create simple XML files, then transformed them into HTML using XSL transforms within a BMC Software product.

Gentle, Anne. WritersUA (2006). Articles>Documentation>XML>Case Studies

Just Say "Help": Implementing Help in VoiceXML

One of the exciting aspects of XML is the number of ways it is being used to provide new means of communicating and gathering new information. One such use is VoiceXML, an emerging W3C standard that brings voice to the Web or the Web to the phone.

Beebe, Allen. WritersUA (2002). Design>Documentation>XML

Microsoft "Longhorn" Help Highlights

Microsoft’s specification for 'Longhorn' Help represents a major revolution in user assistance development for the Windows platform. Instead of simply refining the technical infrastructure of Help (windowing, links, search, etc.), Microsoft has given a good deal of thought to the needs of both Help authors and end-users.

Ellison, Matthew. WritersUA (2003). Articles>Documentation>Operating Systems>Microsoft Windows

Migrating from HTML to XHTML and XML - Part I

This is the first part of a two-part article describing a detailed methodology for migrating HTML files to the structure and flexibility of XHTML and/or XML. By using XHTML to add structure and separate content from presentation, you'll be better positioned for a move to XML. Even if you never move to XML, your XHTML files will be easier to create and maintain, and will be more accessible.

James-Tanny, Char. WritersUA (2006). Design>Web Design>Standards>XHTML

Migrating from HTML to XHTML and XML - Part II

This is the second part of a two-part article describing a detailed methodology for migrating HTML files to the structure and flexibility of XHTML and/or XML.

James-Tanny, Char. WritersUA (2006). Articles>Web Design>Standards>XHTML

A Mixed Bag of Job Prospects for Tech Writers

One of the areas the 2001 ITAA survey looks at is supply and demand. Of the estimated 258,332 jobs that IT hiring managers predict they will add this year, only 1,799, or less than 1%, are for tech writers. This is down a whopping 91% from the year 2000 where the 20,773 available tech writer jobs accounted for almost 5% of the total. The news may not be as bad as it sounds. On the supply side, there is an expected shortfall of 1,008 qualified candidates in filling the open tech writer jobs.

Welinske, Joe. WritersUA (2001). Careers>Writing>Technical Writing

Non-Fatal Errors: Creating Usable, Effective Error Messages

It's often easy to identify what kinds of error messages don't help users, but it can be tricky to avoid them, and even more of a challenge to create the opposite: error messages that give users a clear indication of the problem, offer information to help them fix it, and provide tips on how to avoid the same situation in the future. This paper details the steps involved in creating understandable, helpful error messages, and suggests ways of communicating the value of good error messages to managers and executives.

Wilska, Emily. WritersUA (2004). Articles>Documentation>User Centered Design>Online

Online Communities for User Assistance Professionals

Online communities have become a very valuable source of assistance for answering questions unique to our industry. This article provides an introduction to online communities and describes how to access a few of the most useful sites.

Martin, Chuck. WritersUA (2004). Articles>Collaboration>Community Building>Help

Outsourcing Documentation Development: Assessing the Offshore Option

This paper discusses some of the aspects that should be considered when evaluating the required resources and total cost of offshoring documentation development. As consultants to the documentation industry, The Integrity Group is committed to recommending the overall best solution for each business need. We have, therefore, drawn some conclusions from our research and made recommendations for those who are considering offshoring.

Clifton, Deborah. WritersUA (2005). Careers>Documentation>Outsourcing>Offshoring

Problems in Navigating Online Help: Clues from User Search Patterns

The largest problem our participants had in using the help system wasn't in processing the procedural information in the help, but rather finding the correct help topic, a topic generally unaddressed in the literature on how to write a help system. Specifically, participants had difficulty in searching for topics because their terminology differed from the terminology used by the help system, and they became lost in the unclear structure of the system.

Krull, Robert and Angela Eaton. WritersUA (2005). Articles>Documentation>Help>Online

Putting the "Technical" in "Technical Writer"

By becoming more technical, you can interact more efficiently with software developers and qualify for a greater variety of software documentation projects. This article outlines ways to learn more about three prevalent technologies: programming languages, databases, and Web server technologies.

Owens, David. WritersUA (2004). Articles>Writing>Technical Writing

Review: Review of Cladonia Exchanger XML Editor

This article is a review of the Exchanger XML Editor version 3.2 from the Cladonia company. Being such a broad field, the XML Editor category is necessarily far-reaching, and can cover both database management systems and authoring tools. For this reason, this review narrows the scope by looking at the suitability of Exchanger for use by technical communicators and Help authors to create and edit manuals, user guides and Help systems. Much of the focus of this article is therefore on the software's suitability for DocBook or DITA authoring, and its appropriateness for users without coding skills.

Self, Tony. WritersUA (2006). Articles>Reviews>Software>XML

Review: A Review of RoboHelp Office 2002

This is the first in a series of articles that builds into a personal review of RoboHelp Office 2002. This first article introduces the new release and discusses Topic Templates, Headers and Footers, and the new MS Word Import capability.

Ellison, Matthew. WritersUA (2002). Articles>Reviews>Software>RoboHelp

Review: Review of Screen Capture Tools

Describes the important attributes of a capture tool and examines and compares the features of five popular products.

Ellison, Matthew. WritersUA (2005). Articles>Reviews>Software>Screen Captures

Stairway to Expertise

Tools like Captivate, Camtasia, and TurboDemo make it possible for teachers and communicators to create effective software simulations--without programming. Even simple presentation tools, such as PowerPoint can create truly interactive simulations.

Horton, William K. III. WritersUA (2005). Articles>Multimedia>Interaction Design

Ten Practical Techniques for Single-Sourcing with FrameMaker  

A PowerPoint slide show about using FrameMaker for single-source document creation and management.

WritersUA (2002). Presentations>Content Management>Single Sourcing>Adobe FrameMaker