http://tc.eserver.org/dir/Articles/Documentation/Help A listing of the most recently indexed works about Articles and Documentation and Help 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/Articles/Documentation/Help http://tc.eserver.org/35495.html http://tc.eserver.org/35495.html As I've continued to teach my online RoboHelp class to students who attend from all over the world, one recurring issue has been confusion over the following three RoboHelp features: the start page, the project title and the default topic. The three files/names are totally different, having nothing to do with each other, but are commonly confused. By the time you are finished reading this text, I'm hoping that the confusion is a thing of the past. http://tc.eserver.org/35356.html http://tc.eserver.org/35356.html Provides a historic overview of research on printed software tutorials. Describes developments in design approaches, refinements in design, and user experience. http://tc.eserver.org/35339.html http://tc.eserver.org/35339.html Help authoring tools (HATs) are specialized editors and converters to create online technical documentation. Today, many help authoring tools also provide features for single source publishing, which means that you can generate several output formats and versions from one shared text source. While most tools manage to produce different online formats like browser-based help and compiled help very well, only few tools can also produce printed user manuals (or PDF) of professional quality. Big differences also exist between the tools when it comes to translating your projects into foreign languages. http://tc.eserver.org/35210.html http://tc.eserver.org/35210.html As help systems continue to evolve, whatever name they are called, we will increasingly have to face responsibility for their content, and bring their expertise to what we write. The new systems provide us with all the required tools that tell us the problems with their content. It is up to us to leverage that information to provide better content, and act as ambassadors for products that we write. If writers can go a step ahead, and use their help information to sell products, and reduce the burden on customer support, we would have truly arrived. http://tc.eserver.org/35189.html http://tc.eserver.org/35189.html This Fast Track tutorial demonstrates how to create automatic line numbering in a code block. http://tc.eserver.org/35190.html http://tc.eserver.org/35190.html This Fast Track tutorial demonstrates two methods to call Context-Sensitive Help in a Web Form. We'll discover how Unobtrusive DOM/JavaScript achieves the desired result in calling Context-Sensitive help, and demonstrate how to keep the Structure, Presentation, and Behavior layers of a web page completely separate from one another ensuring good practice with current web standards and accessibility rules. http://tc.eserver.org/35203.html http://tc.eserver.org/35203.html One of the tips for creating a help project is to keeps things simple. This applies as much to the content as it does to the manner in which it is produced. The tool used to produce it has a big bearing on how simple the documentation process is of course but sometimes you just have to bend the rules. http://tc.eserver.org/34889.html http://tc.eserver.org/34889.html Lately I’ve been creating context-sensitive help for an online application. As part of my strategy, I’ve been trying to follow Theresa Putkey’s advice in “Usability in Context-Sensitive Help.” In her article, Theresa recommends providing more than just the steps for a specific task in the context-sensitive help window. Instead, she says to show more contextual links, including answers to why, when, and who questions, because too frequently the user who searches for help may have needs outside the specific task you describe. http://tc.eserver.org/34809.html http://tc.eserver.org/34809.html If you're moving to Flare from another help authoring tool, you'll find that Flare's stylesheet editor is very powerful but different than other stylesheet editors that you may have used. And if Flare is your first help authoring tool, you may find the stylesheet editor overpowering at first. To help you get over that initial hump, Hyper/Word Services offers a stylesheet for Flare that will help you learn to use the stylesheet editor, and that may apply to actual projects. http://tc.eserver.org/34714.html http://tc.eserver.org/34714.html Embedded user assistance is only part of a complete documentation plan. It does not replace the need for other types of content. For example, embedded user assistance is not a good delivery mechanism for comprehensive concepts and detailed discussions of a topic with strategy and best practice guidelines. However, with a strong design, embedded user assistance can support the immediate needs of the user and provide a valuable, contextual link that steers the user into the other parts of the documentation as needed. http://tc.eserver.org/34577.html http://tc.eserver.org/34577.html Although simplicity is a noble ideal, and something like “simplify complexity” could be the mission statement of any technical writer, simplicity is in fact a complex undertaking. The interplay between simplicity and complexity is what technical writing is all about. http://tc.eserver.org/34545.html http://tc.eserver.org/34545.html Do we need to have an external help system? Why not embed help right into the application? Why not take this a step or two further? Instead of having a separate help system, integrate more useful, more robust, and context-sensitive help into the user interface. http://tc.eserver.org/34506.html http://tc.eserver.org/34506.html Context-sensitive help is a practical way to cut down on customer support expenses and add more value to documentation. By providing more complex, context-sensitive help, the usability of the help increases while call center phone calls decrease. http://tc.eserver.org/34507.html http://tc.eserver.org/34507.html Makes the case for embedded help as one of the most effective ways to integrate help within an interface. Although it can be difficult, Bleiel illustrates a way to “elegantly implement and map embedded help.” http://tc.eserver.org/34513.html http://tc.eserver.org/34513.html You can definitely apply some of the concepts of microblogging to crafting error messages. Like a good tweet or a http://www.identi.ca or a jaiku, a good error message must: be concise; contain useful information, for both the person reading it and technical support; and be easy to read and understand. http://tc.eserver.org/34235.html http://tc.eserver.org/34235.html Web site user assistance that consistently exceeds customer’s expectations can catapult your company to legendary status and create brand equity you can measure in billions of dollars. However, making Help a strategic asset for your company is an arduous task. To shed light on this important topic, I have teamed up with Tricia Clement, a renowned cognitive psychologist and Web site user assistance expert. In this month’s Search Matters column, we’ll deliver actionable insights about Web site user assistance. 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/34064.html http://tc.eserver.org/34064.html A short blog post that discusses why users are more interested in learning how to, and not what is. http://tc.eserver.org/33679.html http://tc.eserver.org/33679.html Every help authoring tool seems to have a different approach to presenting search results. Offerings range from ranked results to alphabetical lists, with additional features thrown in such as the inclusion of chunks of topic text with highlighted search keywords. Each method of presenting search results offers different benefits to users. Since help tools offer mixed approaches, I feel perfectly comfortable throwing my own opinions into the mix. http://tc.eserver.org/33634.html http://tc.eserver.org/33634.html As broadband Internet access becomes increasingly available, software providers are minimizing the local installation of help topics and instead moving some or all help to Web servers. While this approach may alienate users who have no Internet connection or lack broadband access, there are many advantages. Web servers offer features and options that aren't available with locally installed help. http://tc.eserver.org/33636.html http://tc.eserver.org/33636.html Software products have found ways to share content and reuse content to deliver more value with limited resources. For example, fantasy football web sites share player news, injury reports, and game statistics. Security products often reuse security announcements and warnings from trusted sources, and present them as rebranded content. We are also seeing software vendors using Twitter and RSS feeds to distribute information and announcements. The next step is when these information feeds are integrated into the product user interface itself, making it the one stop resource for all the information needs of its users. No more need to use google when your product itself delivers the answers to all your questions from the sources you trust. http://tc.eserver.org/33600.html http://tc.eserver.org/33600.html Last month, Forrester Research released results from a survey on how much consumers trust different sources for information. They didn't include online Help or knowledge bases in the survey, so we don't know how well or badly they would have come out in the survey. http://tc.eserver.org/33523.html http://tc.eserver.org/33523.html Knowing HTML alone is not enough to create HTML Help. What deliverables does the client need? CHMs (HTML Help)? Web-based Help (HTML files + other things that create the Toc, Index, Search tabs etc.)? Java Help? Oracle Help? Be aware of the limitations of some formats. http://tc.eserver.org/33335.html http://tc.eserver.org/33335.html Software documentation such as Help systems and user guides may be the best method of helping your customers to use your software effectively. However, one or more of these alternatives may be a better solution. http://tc.eserver.org/33159.html http://tc.eserver.org/33159.html Overview topics play an important role in creating a positive user assistance experience. Unlike procedures, which deliver critical information on how to solve a problem quickly, overview topics fill in the conceptual details and background "story." Here are some tips for writing thorough and informative overviews. http://tc.eserver.org/32979.html http://tc.eserver.org/32979.html Whilst applications are becoming more complex, many people believe that online user assistance hasn't changed much since WinHelp was introduced with Windows 3. This is a misconception. There have been many developments in this field aimed at increasing end-user productivity and satisfaction. http://tc.eserver.org/32980.html http://tc.eserver.org/32980.html Just as a romantic poet might choose to pen an ode to a single rose as opposed to the entire garden, perhaps we should look to the simplest elements of usability for inspiration. Perhaps it’s time to recognize the contribution of a single humble helper. Yes, it’s time for an ode to Balloon Help. You may smile, but it can be argued that Balloon Help is not only one of the most ubiquitous implementations of modern technological performance support but it is also one of the most underappreciated. 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/32376.html http://tc.eserver.org/32376.html Designing online Help for PDAs is a marked shift from designing for personal computers because the reduced memory capacity and display-unit size (a VGA screen of 300x240 pixels) of PDAs mandate Help formats optimized in ways not necessary with larger machines. Current Help files on PDAs are simple HTML files, but this format might prove inadequate for the complex Help files needed for more elaborate software applications. Thus it is necessary to explore strategies for online Help that work within the limitations of small-screen devices. http://tc.eserver.org/32349.html http://tc.eserver.org/32349.html Users turn to help to look for a specific question, just as someone consults an encyclopedia for a specific question. No one reads the entire encyclopedia/manual, nor is anyone expected to. Well-written encyclopedias allow users to find information through indexes, tables of contents, alphabetical organization, and search fields. http://tc.eserver.org/32353.html http://tc.eserver.org/32353.html Flossmanuals.net is a new wiki help authoring/publishing tool hybrid that, as far as I know, is completely unique. The site is more than a wiki. It allows groups of authors to create specific chapters independently. You can then remix the chapters into any arrangement and selection you want through a drag-and-drop interface. http://tc.eserver.org/31992.html http://tc.eserver.org/31992.html So, you've got in trouble. Some or even all of your CHM files seem to have gotten corrupted. They show a "The page cannot be displayed" error in the left-hand pane of the CHM viewer. There are several possible reasons why your CHM e-books and documentation files are unreadable. http://tc.eserver.org/31990.html http://tc.eserver.org/31990.html Are you still wondering which help file format to use for your Windows software? The selection depends on your software and on the information that is in your help files. Each help file format has its own unique features that may be useful in certain situations. http://tc.eserver.org/31988.html http://tc.eserver.org/31988.html There are several main reasons why putting your software manual on-line is necessary. It makes your web-site attractive for search engine crawlers and therefore brings you targeted traffic from Google, Yahoo!, MSN, and other search engines. A good online manual presents your product as serious and credible. Moreover, if a user faces difficulty using your software and asks for technical support, you may easily resolve the issue by referring that user to a certain page of your online help. Simply give the page's URL. With just one click the user will see screenshots and explanations which will help them to resolve the issue. http://tc.eserver.org/31833.html http://tc.eserver.org/31833.html Online help excels in providing quick access to concise information - but only when the users choose to access it. Delivering high-quality online help that satisfies all users is a hard task. Several good help authoring tools make help generation and maintenance easier, but to create good content that is highly effective is still a huge challenge. Experience shows that even after following quality guidelines or best practices, the final output may still not be good enough to satisfy the needs of your users. Heuristic evaluation of an online help system provides an initial assessment of both quality and usability. This article presents a summary of key points for evaluating online help, though you will likely want to expand the heuristics with company or product-centric metrics suitable to your application. 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/31144.html http://tc.eserver.org/31144.html I would argue that 'Presentation Zen' contains ideas that are also relevant to technical communication. http://tc.eserver.org/31112.html http://tc.eserver.org/31112.html There's a lot of great free and Open Source (FOSS) software out there. But one area in which it's lacking is professional-level help authoring tools. In 2005, Linux.com published an article titled "FOSS help authoring tools falter". And not much seems to have changed in the intervening years. http://tc.eserver.org/30826.html http://tc.eserver.org/30826.html According to Jacob Nielsen's How Users Read on the Web, usability of web content can be improved drastically by making content more scannable. Many of his ideas would apply equally well to online help. So, how can technical writers leverage this information to make the help for their product more usable? http://tc.eserver.org/30812.html http://tc.eserver.org/30812.html If you are delivering your help from a network location and you notice that .CHM files don't work anymore, don't be surprised. Recent Microsoft updates include tighter security for .CHM files. After installing the updates you can no longer run .CHM files from a network location. However, you can still run a .CHM file on your local machine. http://tc.eserver.org/30777.html http://tc.eserver.org/30777.html Today, Help authors take HTML for granted. But XML is starting to displace HTML, bringing with it new technologies like DITA and Web 2.0, as well as the potential for disruption. Perlin examines how to prepare for the change through adhering to standards. http://tc.eserver.org/30637.html http://tc.eserver.org/30637.html User assistance is defined as a form of assistance that is provided to users of products to help them use the products more easily and efficiently. In the Information Technology industry, a product is a software product/application that users use to perform specific business functions. Users of these products/applications use them differently, based on their social and philosophical environment, their cultural context, their learnability and a number of other factors. While the same user assistance must necessarily be designed and delivered to the users of a product, because all users use a particular product/application to perform similar tasks, user assistance can be designed and delivered differently to users, based on their social and philosophical environment. This could enable users from diverse social and philosophical backgrounds use the same products/applications more effectively. http://tc.eserver.org/30573.html http://tc.eserver.org/30573.html The design team for a major new product approached our publications group about ideas on developing an online manual and/or online help. Together, we developed a task-oriented, easy-to-use online help system, and continue to work together to evaluate it. Where do we best put the buttons that access the help for various subsystems? http://tc.eserver.org/30499.html http://tc.eserver.org/30499.html In the PC products market, customers insist on excellent support at rock-bottom prices. The traditional model of customer support, having a phone technician answer customer questions, is becoming too expensive. http://tc.eserver.org/30422.html http://tc.eserver.org/30422.html The demand for help and hypertext systems has created a problem for many documentation departments, particularly those in smaller companies and inexperienced in creating these forms of online documentation. The scarcity of existing literature compounds this problem. This document provides writers in small companies with limited resources some suggestions to facilitate hypertext project management, planning, design, editing, and usability testing. Also discussed is how to select a hypertext package. http://tc.eserver.org/30430.html http://tc.eserver.org/30430.html One of the biggest problems facing Help developers is that of providing users with adequate methods of navigation through what can be huge amounts of information. After more than a two or three jumps, users can find themselves in topics that might be useful, but with no clear indication of how they got there or how to return to where they started. OS/2 gives the Help developer extraordinarily flexible tools for creating online documentation that can prevent this situation and provide users with a clearer path through online information than many other platforms can provide. However, this enhanced usability is not without its cost. http://tc.eserver.org/30388.html http://tc.eserver.org/30388.html Caterpillar is dramatically changing the way technical, product support information is authored. Book paradigms have been replaced by the more granular Information Element (IE) approach. The new integrated environment utilizes Unix based, TCP/IP connected, ECALS compliant tools on multi-tasking author workstations. Research data, in-process work approved IE's and relational indices are distributed to work group servers. Application software tools include a graphics editor and an interactive, context sensitive, SGML text editor. The environment is managed by a robust file management system that provides file tracking, revision control, workflow sensitive tool launching, burden planning and management reporting capabilities. http://tc.eserver.org/30247.html http://tc.eserver.org/30247.html Information Presentation Facility (IPF) is the tagging language you use to tag, compile, and debug online information in an OS/2 environment. This workshop This part of the workshop looks at using error log files to examines how to use IPF, provides code samples, and points participants to reference material. http://tc.eserver.org/30135.html http://tc.eserver.org/30135.html This paper presents three methods of user assistance: role models (simple demonstrations), guides (structured walk-throughs), and coaches (active assistants). After a brief introduction, potential uses, available development tools, and additional information sources are discussed for each method. http://tc.eserver.org/30136.html http://tc.eserver.org/30136.html If you are a technical writer or manage technical writers and have been asked to document Lotus Notes applications, this workshop will give you a jump start. You can use the features available in Notes to create an effective help system as a Notes database. This help database can either be a view in an existing Notes application or a stand-alone database linked to the application. In this workshop, you will learn the basics of creating help systems in Lotus Notes. http://tc.eserver.org/29987.html http://tc.eserver.org/29987.html Software user guides have traditionally provided assistance when the user requested help. Context-sensitivity enabled help systems to predict the most appropriate topic to present. For Windows applications, the move from Microsoft WinHelp to the new Microsoft HTML Help format allows user instructions to be presented in the same window as the application. This offers technical authors some extraordinary opportunities to provide intelligent, predictive, interactive help without the user having to request it. In this paper, we will explore one of the first such interactive help systems (for the Archivist e-mail archiving software), and see where the technology is moving. http://tc.eserver.org/29990.html http://tc.eserver.org/29990.html The Help platform for Microsoft Windows is changing once again. Since 1995, Microsoft HTML Help has been the standard for Help systems for Windows applications, but the release of the next generation Windows operating system in 2005 will see a brand new XML-based Help platform. It is currently known as Help.Longhorn, or "Longhorn" Help, or sometimes as Help3 or TrésHelp. http://tc.eserver.org/29988.html http://tc.eserver.org/29988.html There are still many circumstances when drawing a user's attention to changed text is important. How do we do that with Help systems? By borrowing techniques from paper manuals, we don't have to reinvent the wheel. So here's a good approach that will work for Microsoft Word-based HATs. http://tc.eserver.org/29992.html http://tc.eserver.org/29992.html Microsoft HTML Help is actually a suite of technologies. CHM is one part; the HH viewer (a cut-down Internet Explorer with CHM processing abilities) is another. To provide a Table of Contents (TOC) and index for Web-based Help (over HTTP), to support Web applications for example, there are two other Microsoft HTML Help components. One is an ActiveX TOC control, and the other is a Java TOC applet. While these components provide Web-based Help with a TOC, they do not allow context-sensitivity AND a TOC at the same time, because the TOC displays in a frameset. http://tc.eserver.org/29970.html http://tc.eserver.org/29970.html This is a very simple example of integrating a J2SE application with the Apple Help Viewer application. This sample code has been updated to include a project that produces a universal binary. No code changes were required for it to run correctly on Intel-based Macintosh computers. 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/29903.html http://tc.eserver.org/29903.html This panel discussion will explore a specific project conducted by the Mercer Engineering Research Center (MERC) in which existing MERC-designed United States Air Force print-based training was rapidly converted to web-based training. Specific issues discussed are differences in design strategies for print and web instruction, development and authoring approaches, rapid prototyping, usability testing, project management concerns, and lessons learned. http://tc.eserver.org/29760.html http://tc.eserver.org/29760.html 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 paper 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. http://tc.eserver.org/29867.html http://tc.eserver.org/29867.html 'Memory requests for some applications may be denied.' 'Error 404: File not found.' 'Invalid entry. Check your info and resubmit.' 'Fatal error. Procedure aborted.' 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. http://tc.eserver.org/29670.html http://tc.eserver.org/29670.html We examined qualitative data from participants' comments about difficulties they encountered in using the help systems in three versions of a popular programming language. Users' main problems were not knowing which help systems were available or being unfamiliar with them, determining when and how to use the help system, framing the search question, applying the initial search target to the help hierarchy, moving laterally to another topic, and switching between declarative and procedural topics. The lessons learned from these responses should assist help system designers and authors in supporting users' search patterns. In this paper, we will examine qualitative data from users' comments. The lessons learned from these responses should assist help system designers and authors in supporting users' search patterns. http://tc.eserver.org/29432.html http://tc.eserver.org/29432.html It's important to establish and maintain relationships with your audience: it gives you a handle on their changing needs so you can continue to meet those needs. 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/28764.html http://tc.eserver.org/28764.html Discusses a number of trends in the technical writing world, particularly the need to make help more human by adopting conversational tones and addressing the angry/frantic state of the user. http://tc.eserver.org/28028.html http://tc.eserver.org/28028.html MAML is part of a new approach to help in Windows Vista. This approach is both more integrated with the software and more focused on user tasks. MAML provides a structre in which you can write user assistance information, which can then be presented to the user in a variety of locations. http://tc.eserver.org/27797.html http://tc.eserver.org/27797.html For a long time we've been told that XML Help is the future. So is it? In this article, David Rose examines the current state of the online help development industry and the direction it is heading. http://tc.eserver.org/27658.html http://tc.eserver.org/27658.html 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. http://tc.eserver.org/27649.html http://tc.eserver.org/27649.html 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. http://tc.eserver.org/27651.html http://tc.eserver.org/27651.html 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. http://tc.eserver.org/27642.html http://tc.eserver.org/27642.html 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. http://tc.eserver.org/27650.html http://tc.eserver.org/27650.html This article provides an overview of the latest trends in software user assistance based on surveys, interviews, and observations by the author and other experienced user assistance professionals. The article defines the key terminology, highlights the most important issues and elements, and offers both short and long-term predictions for the field. The article will appear in four installments. The next installment will be in February. http://tc.eserver.org/27084.html http://tc.eserver.org/27084.html This article looks at a methodology for developing a software user assistance (UA) system in a structured manner. The software UA system could have both paper-based user manuals and online help systems. http://tc.eserver.org/27030.html http://tc.eserver.org/27030.html Customers avoid web-based customer support if information is not relevant, out of date or hard to find. Without a business commitment to addressing these issues, customers will continue to prefer contacting a service representative by phone. http://tc.eserver.org/26720.html http://tc.eserver.org/26720.html This article takes a look at a methodology for developing and managing a Software User Assistance (UA) System, a way of doing things in a structured manner. It provides a complete walkthrough for managers responsible for designing, developing, and managing a software product’s user assistance system. The software’s UA system could comprise of both paper-based user manuals and online help systems. http://tc.eserver.org/26309.html http://tc.eserver.org/26309.html A brief tutorial on creating cross-platform WebHelp (similar to that produced by RoboHelp) using DocBook. http://tc.eserver.org/26311.html http://tc.eserver.org/26311.html An introduction to using Sun's JavaHelp system for creating online Help. http://tc.eserver.org/26310.html http://tc.eserver.org/26310.html An introduction to XML (Extensible Markup Language) and how technical writers can use it to create and manage their documentation. http://tc.eserver.org/25870.html http://tc.eserver.org/25870.html In order to make a help system really helpful, you need to provide an effective index. But many online help writers face two dilemmas when it's time to index their help systems: How to prepare a useful index that meets the users' needs and how to code the keywords to make the index compile correctly. This article provides tips to help writers solve both problems. http://tc.eserver.org/24972.html http://tc.eserver.org/24972.html This presentation describes a strategy to meet a last-minute enterprise demand for online help for a software application program. We established design standards for writing online help, developed a process for gaining consensus from the project team on the content of the online help, and wrote the online help. We accomplished this in less than four months-a task that originally seemed impossible. http://tc.eserver.org/24925.html http://tc.eserver.org/24925.html Calls on technical communicators to suggest a new term for modular documentation accessible via a tri-pane interface. http://tc.eserver.org/24841.html http://tc.eserver.org/24841.html The Knowledge Products group at Cisco Systems, Inc., provides online help for both PC and UNIX-based applications. The online help team for the Cisco Works for Windows product comprised of five writers who coordinated the online help development efforts. The online help team worked closely to produce an integrated help system that was modularized for better process control. http://tc.eserver.org/24798.html http://tc.eserver.org/24798.html An industry-wide design standard for help systems does not exist. To develop a flexible and usable help system for our workstation-based product, we have evolved and changed our help system design. Over a five-year period our help system was influenced by several factors: http://tc.eserver.org/24805.html http://tc.eserver.org/24805.html Users complain that there is too much information in help. We will explore ways to move beyond help and provide users with the types of support they really need: re-using information on commercial information services such as CompuServe or America Online, on the Internet, and on dial-up phone and fax services. Making application interfaces self-documenting. Providing information in overlaid notes, cue cards, and wizards. http://tc.eserver.org/24801.html http://tc.eserver.org/24801.html How do you create an effective online help system and efficiently manage the project? This paper will cover some basics of practical online help design and project management. The presentation includes examples from a project we worked on. http://tc.eserver.org/24766.html http://tc.eserver.org/24766.html Two main forces affect a Help project: absurd deadlines and a complex web of hypertext files. Those responsible for managing such projects often ask: How do I gain control of all these forces? When do I need to start the project? How do I gauge its progress? Our demonstration will show how to successfully manage a Help project. We will illustrate how WordPerfect Domestic Documentation Services solves management problems using a timeline, checklist, and tracking database. http://tc.eserver.org/24729.html http://tc.eserver.org/24729.html In the eras of Windows 3.x and earlier versions of Windows 95, the only help system people worked with or even knew about was WinHelp. Problems started with the transition to Windows 95, when developers and users alike had to learn to deal with WinHelp 4.0's separate dialog with the Contents, Index, and Find tabs. http://tc.eserver.org/24679.html http://tc.eserver.org/24679.html Adapting new equipment to your complete array of jobs, and leveraging your new investment to help your business grow and become more competitive, is part of an ongoing process that is much more important that the initial implementation. It's a process that requires an on-going partnership and several levels of support from your technology vendor-- beginning with basic maintenance and repair and optimally evolving to a true interactive partnership. http://tc.eserver.org/24658.html http://tc.eserver.org/24658.html Just as clothing styles change, and fall's fashion is different from summer's, so Microsoft presents it's new fall's fashion of online help to a fashion-consious entourage of software companies always eager to follow Microsoft's lead. http://tc.eserver.org/24510.html http://tc.eserver.org/24510.html With planning, an understanding of organizational devices such as expandable tables of contents, secondary help windows, and graphical navigational aids, you can make your help system easier to use, more attractive, and more useful. http://tc.eserver.org/24430.html http://tc.eserver.org/24430.html The basic requirements for creating accurate and useful technical documentation are good writing skills, an understanding of the audience, knowledge of the tools used for producing documentation, ability to use the product, and ability to successfully interview subject matter experts. While the same skills are essential for creating an online help system, writers also need to understand how help projects are set up, how to modify their writing to produce modular help topics, how to test the program-to-help links between the product and the help topics, and how to align help file development with engineering build dates. In addition, writers expand their hypertext awareness to include new terms such us jumps and pop-ups. http://tc.eserver.org/24410.html http://tc.eserver.org/24410.html IDX Systems launched two separate HTML-based help authoring efforts simultaneously. The results were two very different HTML-based help solutions. One solution emphasized thorough and complete information while compromising accessibility. The other solution emphasized accessibility while compromising thoroughness and completeness. In both cases, the compromises were forced by the limitations of current web technologies. The two writing efforts have now been merged into one solution that uses HTML, database technology, and Active Server Pages. http://tc.eserver.org/24407.html http://tc.eserver.org/24407.html Technical communicators are facing a revolution in how we develop online help for software applications. No where is this more apparent than in the development of help systems for applications written in Java. Sun Microsystems, Inc., expects to roll out JavaHelp in the early part of 1998. Until JavaHelp arrives, technical communicators will have to find creative ways to implement HTML help systems for Java applications. The best news is that we have some standards to follow, like HTML, and some methods for browsing HTML help today. The key is to develop scalable help systems designed with the future in mind. This paper discusses some ways you can create HTML help content that works with your applications today and tomorrow. http://tc.eserver.org/24326.html http://tc.eserver.org/24326.html We have all heard the terms, ‘telecommuting,’ ‘groupware,’ and intra- or internet at one time or another. However, the best designed information retrieval system is useless if you cannot get on-line to use it. Most companies are taking advantage of technology, and publishing their policies and procedures on their own intranet or Local Area Network. Unfortunately, some organizations with field offices, off-site agents or consultants, even executives on travel are not always ‘plugged-in’ to this information. There is a way to make dynamic information available to enterprises without internet accessibility or LAN/WAN connections. What follows is one solution to the quest for getting ‘plugged in’ and taking advantage of dynamic data exchange. http://tc.eserver.org/24320.html http://tc.eserver.org/24320.html This paper describes an online documentation delivery and feedback solution developed to meet the needs of a fast-paced project in which designers, developers, marketing specialists, technical writers, and beta-test customer sites were located all over the world. During the development of the IBM Health Data Network, we needed a way to provide drafts of the product documentation to all of the developers, reviewers, and users on a real-time basis. We also needed a way to get input and updates from the developers, and feedback from the people in the field who were working with beta versions of the new system. This paper describes how we set up a Web-based solution to meet these needs. http://tc.eserver.org/24307.html http://tc.eserver.org/24307.html How do customers expect to access online Help? Once in the Help system, how do they expect to navigate toward the information they need? In the absence of detailed research that tells us what customers know about getting and using online Help, we can look for clues in the marketplace. A survey of the Help systems in more than sixty Windows 95 applications (including those in the major suites from Corel, Lotus, and Microsoft) shows some clear trends. These trends can help us understand what customers are coming to expect from online Help based on their experience with other Windows 95 applications. http://tc.eserver.org/24302.html http://tc.eserver.org/24302.html Information types are a new feature of HTML Help, but they are not a new concept to technical communication. Information types are simply categories of information that can be assigned to a discrete piece of information so the information can be displayed or hidden, based on the category selected by the user. The goal of this paper is to get help authors thinking about ways that they can use information types to help their users filter, sort, and understand the structure of the information presented to them through online help. http://tc.eserver.org/24290.html http://tc.eserver.org/24290.html As a consultant I get called in after the wreck to figure out what went wrong. Across a wide range of industries and products, the same problems recur again and again. In this presentation, I’ll show you what these common problems are and simple ways to avoid them. http://tc.eserver.org/24274.html http://tc.eserver.org/24274.html In the transition to online documentation, one of the communicator’s most effective tools can be a hardcopy document. Providing your users with a printed manual that introduces them to your product and your online documentation might be just the thing they need to get started using both. To create an effective hardcopy document, you must begin by gathering feedback, analyzing your audience, and setting your goals. You can then use that information to determine what to include, what to exclude, and what to call your hardcopy document. http://tc.eserver.org/24258.html http://tc.eserver.org/24258.html If everything on the desktop was proceeding as planned, nobody would ever press F1. But people do press F1--a lot-- and it’s our job to give them the information they need when they need it. This paper suggests design strategies, organizational strategies, and writing tips that can help make the information in your WinHelp files more accessible. http://tc.eserver.org/24212.html http://tc.eserver.org/24212.html There are many roles involved in developing a successful online help project. Understanding the relationship between these roles can increase everyone's awareness of the requirements and tasks necessary for a successful project. In many projects, individuals fill more than one role, moving between roles as needed. http://tc.eserver.org/24074.html http://tc.eserver.org/24074.html Basic steps to developing successful online help include content planning based on available resources and user needs, use of a style guide, effective design and access, prototype development, usability studies, and being open to changes. Defining “quality” as “customer satisfaction” we can place the online help development process into the context of a continuous quality process model that focuses on meeting customer needs. This quality process includes identifying output, identifying customer and customer requirements, converting requirements into processes, measuring the output, and evaluating results. http://tc.eserver.org/23851.html http://tc.eserver.org/23851.html Advances in technology in the last ten years have created an emerging category of portable online computers (Pocket PCs or PPCs) that offer a wide range of product features comparable to Personal Computers (PCs). Improvements in PPC hardware specifications and the growing numbers of compatible software applications are resulting in an increased (and multi-faceted) user base. Increasing technical capabilities, advanced product features, and a diversified user base are creating new challenges to design online Help systems that can satisfy user needs and requirements effectively. http://tc.eserver.org/23800.html http://tc.eserver.org/23800.html Designing and developing an embedded help solution involves several stages. A successful solution starts with identifying user wants and needs. As you sort through these needs, identify common threads and design a solution that addresses these common threads. Consistency, flexibility, and experimentation are keys to developing a successful solution. Your design should be intuitive to use, and should provide users with the options they need. As you design your solution, consider your develop and maintenance requirements. You want the time you invest in the first version of your solution to pay off for future releases. http://tc.eserver.org/23739.html http://tc.eserver.org/23739.html With new tools and technologies available, more companies are choosing to move from paper-based documentation to electronic documentation. Being a pioneer is an exciting – and daunting – experience. In moving from paper-based to electronic documentation, you may be treading on a path never before explored for your product or your company. There are many decisions to make and many plans to develop, abandon, and develop again. Special attention is required in the areas of project management, writing and illustration, documentation design, and configuration management. A team that has experienced a paper-to-electronic documentation project can offer valuable advice if you are facing a groundbreaking project. http://tc.eserver.org/23733.html http://tc.eserver.org/23733.html This paper reviews research done in online help information, analyses different views on it from the perspectives of professionals of technical communication and end-users, and suggests ways to solve problems. http://tc.eserver.org/23734.html http://tc.eserver.org/23734.html Accessibility is about providing successful access to information, and the use of information technology by people who have disabilities. The IBM® WebSphere® Commerce development team adopted IBM’s mandate to make its software accessible, and achieved a high level of accessibility in its release of the IBM WebSphere Commerce, Version 5.4, suite of products. Continuing with the next release, the WebSphere Commerce development team strove for an even higher level of accessibility. This paper discusses some of the experiences and lessons learned from making WebSphere Commerce online help and software accessible. It examines some of the most common issues from the User Experience, Information Development, and Test perspectives. http://tc.eserver.org/23727.html http://tc.eserver.org/23727.html Resources relating to user guides and online help systems. http://tc.eserver.org/23661.html http://tc.eserver.org/23661.html Online help systems have evolved over the past twenty 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. http://tc.eserver.org/23141.html http://tc.eserver.org/23141.html The user's idea of the problem is often very different than the help or program designer's. The online help topics often reflect the designer's viewpoint, not the user's. http://tc.eserver.org/22918.html http://tc.eserver.org/22918.html The panelists provide examples of standards for visuals that reduce text and increase access in online Help. They briefly cover how these visuals solve problems for both customers and Help designers, and they discuss standards for two of the visuals selected for the session. Audience ranking determines the order of the remaining visuals. In covering the visuals, the panelists use examples from Help for highly sophisticated engineering, applications whose users have varying levels of experience and comfort with computer software. The panelists also provide checklists for developing standards, including standards for how information should look and, more importantly, work. http://tc.eserver.org/22860.html http://tc.eserver.org/22860.html Maximizing Windows Help is more than just converting printed documentation to Help. Help users want easy access to information so that they can complete their tasks expeditiously. A Help topic should contain information that adresses one subject, has one objective, and answers one question. To maximize Windows Help, chunk information and use hyperlinks. The use of macros can enhance how information is accessed. http://tc.eserver.org/22262.html http://tc.eserver.org/22262.html Last month I went through some fairly atrocious documentation. The letters I received from frustrated geeks really drove home the point that bad docs can make what should be a simple, routine, and--dare I say--fun experience, dreadful. http://tc.eserver.org/22164.html http://tc.eserver.org/22164.html Weber State University is in the process of developing a major in Professional & Technical Writing (PTW). Currently, students enroll as English majors with an Emphasis in PTW, which consists of four courses in PTW that students take in addition to other English courses. The minor consists of the same PTW courses plus two interdisciplinary classes, which are determined in consultation with an advisor. The problem is that students who wish to do PTW must take the same number of literature classes as other English majors. Often they do not receive instruction in document design, other than a cursory treatment in the service course. A full major would better prepare students to enter the job market without losing connections to critical theory and humanistic approaches to texts-connections they receive in English Department courses. http://tc.eserver.org/22119.html http://tc.eserver.org/22119.html This paper describes some common types of help topic and when to use each. Different applications require different mixes of help topics. Choose the topic types that are appropriate for the application you are documenting. http://tc.eserver.org/22118.html http://tc.eserver.org/22118.html This paper outlines some general principles you need to consider when planning an online help project and creating WinHelp files. http://tc.eserver.org/21795.html http://tc.eserver.org/21795.html Why would anybody want to use JavaHelp? The answer is not necessarily obvious, especially to help authors. http://tc.eserver.org/21707.html http://tc.eserver.org/21707.html An overview of documentation development for online help. http://tc.eserver.org/21574.html http://tc.eserver.org/21574.html When assigned to create a context-sensitive hypertext Help system, writers and editors often find themselves asking, 'Where do I start? What is context-sensitivity and how in-depth should it be? How do I organize Help topics for the interface?' We will demonstrate how to structure a Help system based on context-sensitivity, the interface, and useful access tools. We will show how WordPerfect Domestic Documentation Services uses interface information to create a topics database and a corresponding text file. http://tc.eserver.org/21505.html http://tc.eserver.org/21505.html A browse sequence enables users to navigate through a series of help topics in the sequence established by the help author. Although often omitted from help systems, the browse sequence is useful and will become essential as print documentation diminishes. Effective design options for a browse sequence include multiple segments, rings, branching, and the use of a browse button to take the user to the first topic in the current segment of the browse sequence. http://tc.eserver.org/21506.html http://tc.eserver.org/21506.html We are currently in the second phase of development of a large Windows online help system. This paper reviews the major decisions we had to make during the first phase of the project, and lists some project evaluation results that have helped us plan for subsequent phases. http://tc.eserver.org/21479.html http://tc.eserver.org/21479.html With the advent of HTML Help and the ability to embed Help directly inside an application, there's been an increased interest in creating Help systems that are seamlessly integrated with their host applications. By blurring the line between the application and the Help that supports it, and by developing Help that automatically responds to user actions, application developers and Help authors now have the ability to develop true electronic performance support systems. http://tc.eserver.org/21471.html http://tc.eserver.org/21471.html Microsoft’s HTML Help presents a dilemma to Help authors who wish to deploy it on web sites: Should they use the ActiveX control to provide faster, more robust functionality, or should they use the Java applet to provide wider compatibility? This article shows how you can have the best of both worlds and create one HTML Help system that will be optimized for viewers regardless of whether their browser supports ActiveX or Java. http://tc.eserver.org/21475.html http://tc.eserver.org/21475.html In a previous article we discussed what browser-based HTML Help is, and how you can use the HTML Help ActiveX control to create and distribute web-based HTML Help to Microsoft Internet Explorer Users. In this article we'll explain how to use the Microsoft Java Applet to create and distribute Help systems that can be viewed by an Java-enabled browser. http://tc.eserver.org/21480.html http://tc.eserver.org/21480.html In this article we discuss what browser-based HTML Help is, the sitemap file that's behind the HTML Help table of contents, how the HTML Help ActiveX control HHCTRL.OCX interprets and displays this sitemap file, and how you can automatically distribute HHCTRL.OCX. http://tc.eserver.org/21473.html http://tc.eserver.org/21473.html Doc-To-Help 2000 has a new 'fault tolerance' feature that forgives novice authors their Microsoft Word mistakes, including direct formatting and stretched bookmarks. These problems often cause corrupted cross-references as well as document-to-Help-system conversion problems. Doc-To-Help's automatic diagnostic and repair utilities now find these common errors and correct them automatically. http://tc.eserver.org/21472.html http://tc.eserver.org/21472.html JavaHelp is a new online Help platform created by Sun. Sun released JavaHelp 1.0 in April, but it's been publicly available through several beta releases for a while. (The just-released Doc-To-Help 2000 supports this new version of JavaHelp.) http://tc.eserver.org/21457.html http://tc.eserver.org/21457.html Below you can find a compilation of the most frequently asked questions about electronic catalogs. You will find answers to general as well as to technical questions. http://tc.eserver.org/21435.html http://tc.eserver.org/21435.html Benutzerinstruktion muß sein. In Form von Online-Documentation ist sie unmittelbarer Teil des Programms. http://tc.eserver.org/21385.html http://tc.eserver.org/21385.html This article lists the basic differences between WinHelp version 4, Microsoft compiled HTML help, WebHelp and pure HTML help. Samples are available.