northbay news, may/june 2001 northbayhttp://www.stc-northbay.org/ news The monthly newsletter of the NorthBay Chapter of the Volume 8, Number 5, May/June 2001 Society for Technical Communication Is Help Online? John Dibs, NorthBay News Editor

At our May meeting, Gary Farrell of Agilent Technologies in Santa Rosa presented some thoughts on help systems in general and demonstrated his online help expertise.

This poor guy looks like he Sophisticated Help needs some help...fast! Gary began by characterizing the different help systems in use. At the ✾ Is Help Online? lowest rung of the sophistication ladder stand portable document format files. Distilled from FrameMaker or Word files, PDF files, ✾ President’s Column with or without hypertext navigation, are sometimes used to post electronic documents on ✾ This Month’s Meeting the Web in lieu of an integrated and compiled online help system. With the next crudest form of online help, WebHelp, HTML files can function as a help system using navigation ✾ Heavy XMetaL features. The user loads this type of system onto their computer when installing the program. ✾ ASI Golden Gate Chapter’s 18th Continues on page 3 ☞ Annual Conference President’s Column By Kurt Huget, President

As most of you know, officer elections were held at our March chapter meeting. Once again, we proved that democracy works. There was an orderly transfer of power, with no soft money involved, no Supreme Court intervention, and no revolution in the streets. Just what you’d expect from a gathering of levelheaded technical communicators.

With the final vote count tabulated, I am honored to have been selected and confirmed as chapter president by my peers. I look forward to fulfilling my duties with dignity, and I will approach this as a learning experience: an opportunity to learn more about my profession, my fellow STC members, and myself.

I follow in the footsteps of John Dibs, his predecessors, and their exemplary work. John did a grand job as president, with many notable accomplishments, such as his work shepherding along the STC grant proposal to develop a local technical communications curriculum. Continues on page 7 ☞

1 northbay news, may/june 2001

northbay officers and committee chairs This Month’s Meeting president Thursday, June 21, 2001 kurt huget [email protected] InfoPros Presents Writing for the Web co vice-presidents barbara herbert [email protected] Presenters: Caroline Drakeley and Anne Marie Smith chris muntzer [email protected] Communicating in the world of hypertext successfully so that your newsletter editor: john dibs ([email protected]) message is read and understood requires applying specific online layout: mary e. flynn ([email protected]) information principles and using effective, proven techniques. In this web session, attendees will gain the knowledge and techniques necessary to trudie folsom ([email protected]) write effectively for a computer-based hypertext medium. Specifically, membership the attendee learns how to do the following: will ross ([email protected]) • Adjust writing styles from linear to modular hospitality • Group and nest information so the reader doesn’t get gabrielle de serres & kathy cia “lost in hyperspace“ treasurer liz kaiser • Structure information for quick lookup [email protected] • Layer information for different user levels • Label information effectively for easy access • Say more with fewer words and in less space

Anne Marie Smith and Caroline Drakeley, are President and Chief Executive Officer, respectively, of InfoPros, a Sacramento-based technical communication firm they began in 1995. InfoPros offers a range of technology-related services, including Web site design and content development, information architecture consulting, site usability submitting articles and ads analysis and testing, technical documentation, and instructional and We welcome articles, advertising, and news about meetings, workshops, and courses that pertain to technical multimedia development. InfoPros, which currently has 45 employees, communication. Please e-mail simple text to the editor at [email protected]. has been listed as one of the fastest 100 growing companies in Advertising rates (per issue): $20 for 1/4 page, $35 for 1/2 Sacramento by a local business newspaper for the past two years. page.

reprints and distribution Smith (B.A., Communications) has been in the technical If you reprint articles from the northbay news, please communication field since 1984. Drakeley (B.A., M.B.A.) has over credit them and forward a copy to the editor. Reprints in non-STC publications are subject to the author’s approval. sixteen years experience in the publishing, marketing, and technical Copyright © 2000 northbay news. northbay news is free to NorthBay Chapter members. communication arenas. Drakeley and Smith are also instructors in the Nonmember subscriptions in hard copy are $12 per year. CSU, Sacramento Technical Writing, Train-the-Trainer, and E-business certificate programs. They frequently speak at both national- and local- level conferences in the area of online communication, marketing, and e-business. Continues on page 7 ☞ Meeting Schedule

STC Mission Statement LocationLocation: Parker Compumotor, 5500 Labath Dr., Rohnert Park The mission of the Society for Technical Timeime: 5:30 - 6:30 Networking and Refreshments Communication is to improve the quality and effectiveness of technical 6:30 - 8:15 Introductions and Program communication 8:15 - 8:30 More Conversation, Idea Swapping for audiences worldwide.

2 northbay news, may/june 2001

Is Help Online? its .chm file, you can place these files on WYSIWYG editor, but you can use an HTML Continued from page 1 the Web, e-mail them to a friend, or editor (many of these are free) for shaping Macromedia Dreamweaver is an example distribute them through just about any up the help topics. Existing HTML files can of an application utilizing WebHelp. Still, means. be added and all links will be compiled. WebHelp systems can be cumbersome. All the features of RoboHELP can be At the heart of HTML help files lies the reproduced using this free tool, since HTML Next in order of sophistication comes hhctrl.ocx ActiveX Control. In order to view Help Workshop uses the same hhctrl.ocx WinHelp, the most popular form of online .chm files you need the hh.exe file on your file. help for many years. WinHelp presents a computer, along with Microsoft Internet familiar help application pane with the Explorer. In addition, an .hhp file So why purchase RoboHELP? As Gary help topic on the right and contents, (analogous to the .mpj file in WinHelp explained, the values are four: search, and index tabs along the left. Gary systems) keeps track of the innards of your · Reports can be generated for broken pointed out the annotate feature in project, such as the links. For more links, images, and style sheets used in WinHelp, something not yet available in information, Gary pointed us to the help project. HTML help. WinHelp2000 from eHelp, the Microsoft.com/ms.htm and suggested we · RoboHELP includes wizards for the developer of RoboHELP, offers a new flavor index and glossary. of WinHelp, but requires a rather large · A good HTML editor is included with roboex.dll file in order to operate. RoboHELP the product. · Various help outputs can be generated, DHTML Finally comes Microsoft HTML help, the such as WebHelp and print versions of your help system. star of Gary’s show. HTML help has a look WinHelp and feel similar to a browser, with navigation buttons along the top. To complete the picture, such systems as Contents, index, and search tabs, as well as JavaHelp and OracleHelp also deliver optional glossary and favorites tabs, can be online content. JavaHelp, an online help used for navigation. application, is also free from Sun Microsystems, or Java-based help files can be generated from eHelp’s RoboHELP Stored on each of product.

our personal Is Help Helpful? What is DHTML? computers are Surprisingly, it’s not scores of help search for “HTML Help.” HTML help does have some limitations. a separate markup systems. For example, HTML help doesn’t support all the secondary window features that language. WinHelp supports. Also, it does not provide The In-Nerds of Help a method for forcing help topics to display at the top of the user’s screen. Stored on each of our personal computers Bells and Whistles Using are scores of help systems. To view the help DHTML files in Windows, view a list the files on Two Ways to Help What is DHTML? Surprisingly, it’s not a the c:/windows/help directory. Compiled RoboHTML too expensive? Try separate markup language. Rather, it’s a WinHelp files have .hlp file extensions and downloading HTML Help Workshop, a free method of using JavaScript or Visual Basic HTML help files have .chm extensions. application, from Microsoft’s Web site for Script programming to manipulate HTML Since all the contents and features of an developing your online help. There’s no HTML online help system are contained in Continues ☞

3 northbay news, may/june 2001 or cascading style sheet elements. As one HTML code, or be set off in a js file existing documents and adapted them for member of the audience succinctly put it, (eHelp’s method). Help authors can even online use. For online help content, DHTML is the “knowledge of how to use use NotePad to edit the HTML files. brevity was the rule. Sentences were made JavaScript or VB Script within HTML.” to the point, with no fluff or hype. Another Gary showed his online help version of convention was to include a brief overview DHTML performs the following feats: topic tabs, the code for which he or bullet list of the help topic at the top of · Image swapping borrowed from an HP site. Clicking on the help window to give users a clear idea · Text mouseover the tab brings up the specified topic. of what’s covered. · Fly-in effects Another feature in Gary’s help system was · Glow effects the use of an animated .gif file of an · Popup windows arrow that displays in the lower right With embedded corner of the screen, next to a scroll bar. The arrow remains in the same location help, help content is JavaScript can either on the help window independent of the user’s vertical scrolling and allows a not a separate be embedded into quick way to navigate to the top of the help topic. application the HTML code, or be launched from set off in a js file product software; (eHelp’s method). rather, it is part of the user interface. Gary explained that almost all DHTML uses JavaScript, whereas early in his online help career, he chose to use Visual Basic Script, Gary’s final comments included praise for only quickly to discover that no one else was the online help included in products such using it. RoboHelp has a built-in an as Microsoft Money, where the help interface for implementing DHTML, so help content is integrated into the application. authors do not necessarily need to know His comments underscored the conclusion JavaScript in order to take advantage of of Andrea Ames in her presentation last DHTML. year on embedded help systems.

Demonstrated Help At the end of the presentation Gary With embedded help, help content is not a demonstrated an online help system that he separate application launched from has worked on over the course of the past Most help systems work a little bit better than this. product software; rather, it is part of the three years. The system employs DHTML and user interface. This seems to be the cream .gif images to create menu options for of the help system crop when it comes to navigating within the product’s help system. usability. With embedded help, the Image swapping during mouseover In closing, Gary fielded some questions application itself, and not a help substitutes an image of a button with a about his approach to creating Agilent’s component, guides the user through task- button having an outline giving the visual online help system. He indicated that oriented steps and troubleshoots along the effect of the mouse selecting the button. writing took most of the effort, while way. Behind the scenes, JavaScript is swapping fitting the content into a style sheet for one image for another. Gary explained that consistency took relatively less effort. In JavaScript can either be embedded into the order to come up with content, Gary used ✍

4 northbay news, may/june 2001

Heavy XMetaL Element and attribute relationships are critical to a well-formed XML document, John Dibs, NorthBay News Editor and XMetaL includes several features for Barbara Herbert, NorthBay Chapter managing these rules. Jay demonstrated how XMetaL can streamline content If you missed our April chapter meeting, creation with a customizable drop down you missed a demonstration of XMetaL list of allowable metadata labels that and a discussion about extensible markup enforce the rules of your XML document. language (XML) given by SoftQuad Another example of XMetaL’s versatility is Software’s representative Jay Di Silvestri. its ability to change the attribute order in Jay joined us along with Janis Peterson of ordered lists from Arabic numbers to SoftQuad for this presentation. Attendees Dude, like, XMetaL rocks! alphanumeric and vice versa by using an received SoftQuad coffee mugs, a nice ORDR attribute as a sort criterion. The marketing flyer on XMetaL, and coupons demonstration showed XML content in good for $100 off the XMetaL list price. both WYSIWYG view and XML view. Who’s into XMetaL? Some may remember the somewhat As Jay explained, XML applications are best exhaustive presentation on XML given by implemented after a thorough analysis of Berkeley STC chapter president Sarah Lee Element and company information usage patterns, an analysis that SoftQuad, not surprisingly, attribute provides as one of its XML solution services. XML applications For companies who have migrated to XML, relationships are XMetaL functions as a front-end interface are best for managing XML content. critical to a well- implemented after formed XML For those of us not experienced with using a thorough analysis XML-based content for documentation document, and purposes, XMetaL looked both familiar and of company futuristic at the same time. Touted by XMetaL includes SoftQuad as the “premier enabling information usage technology for XML-based content several features for patterns. applications in electronic publishing, e- managing these commerce, and knowledge management,” Jay explained that with XmetaL, rules. “structured XML documents are created Hauslinger a while back. Jay kept the with the ease of using of word processor.” discussion of this extensive topic down to an hour. Using XMetaL, content from other Jay also demonstrated Resource Manager, applications such as Word or Excel can be which he described as the most powerful Based in Toronto, Ontario, Canada, pasted directly into the XML document. Jay feature in XMetaL. With this utility, users SoftQuad Software also keeps a strategic indicated that with some work, data can be can drag and drop files, URLs, and images presence in Petaluma. SoftQuad lays linked to the original file so that updates to from other locations or from the Internet claim to an early involvement in the the source file would automatically be directly into an XMetaL document. In adoption of the XML 1.0 standard by the reflected in the XMetaL XML file. From addition, when content reuse is called for, WC3 (World Wide Web Consortium). XML, documents can be formatted for material from an XML document (such as SoftQuad is also the developer of either browser viewing or portable warning messages) can be placed in a HoTMetaL, an HTML authoring tool document format (PDF) using an common area for reuse. popular among Web developers. extensible style sheet (XSL). Jay explained how XMetaL works as an Continues ☞

5 northbay news, may/june 2001 interface with content management reference to its tag name, which describes Another question came up about whether systems (CMS) such as Documentum. CMS what the information is, not how to style it’s best for clients to develop their own workflow tasks, such as checking a it or how to process it. DTD or use one already developed, such as document in, can be incorporated into DocBook. SoftQuad characterizes DocBook XMetaL. as being tailored to software XML enables the creation of a deeper structure for the information and makes possible Single-sourcing lets us put one thing in...... and get many things back! feats such as documentation, having lots of elements content reuse and and resources, and requiring training in XML Basics order to use effectively. According to Jay it After whetting our appetite with a new document is cheaper to develop your own DTD, then authoring tool, Jay moved into a portability among implement the required XSLTs for discussion about XML. A common conversion to output formats such as approach to understanding XML is multiple vendors. HTML or PDF. XMetaL version 2.1 doesn’t comparing it to HTML. HTML tag names currently support XML schemas, which also have specific format-related meanings, have yet to be added to the XML standard and it isn’t possible to create custom tags. by the WC3.

In short, HTML tags make information With XML, data intelligible by computer applications SoftQuad’s Process (such as browsers), whereas XML tags make SoftQuad’s approach to XML conversion becomes self- information intelligible by humans as projects starts with the people who will well as by computer applications. XML create the content. As Jay explained, “a lot describing by enables the creation of a deeper structure depends on authors, and how receptive they for the information and makes possible will be to structured writing.” For reference to its tag feats such as content reuse and document example, what name, which portability among multiple vendors. describes what the In response to a question from the Rather than design audience about when to develop a DTD, or information is, not document type definition, Jay described the most complex SoftQuad’s approach. Rather than start how to style it or with the DTD, an XML conversion project system, it’s better to results in a DTD that conforms to the start simple. how to process it. business requirements of the client. As Jay conveyed, during consulting projects, SoftQuad must often overcome the By contrast, XML tag names serve as labels assumption that a DTD is required upfront authoring software do they currently use, for data rather than for formats and can be in the conversion process. (A DTD defines and how consistently do they apply tags or customized to fit the needs of the content. the structure of an XML document.) styles? The concept of granularity is With XML, data becomes self-describing by Continues ☞ 6 northbay news, may/june 2001

Finally, design matters are hammered out. important. As Jay explained, more The design of any XML application must The rewards for conversion to an XML metadata means more work, whereas “a reflect the people and system analysis application can be tremendous. For a set of simple data model means that authors conducted earlier. To arrive at a well- technical manuals for cars, for example, don’t need to know XML” in order to do developed DTD or XML schema, the process much of the content will be the same, their job. Rather than design the most of “design, test, and iterate” must be while some of the content will vary by complex system, it’s better to start simple followed. If information is overly complex, model, by year, and by options. The and revisit the need for granularity six clients must work through the causes for documentation can be structured using months after implementation. the complexity to determine whether the XML so that repair steps will be linked to complexity can be justified. the actual symptoms, to the actual car in After the people angle, SoftQuad next looks question, and to the appropriate parts lists at system considerations, such as which Data Structure for the identified model and year. content management system the client Jay presented some basic concepts about While brief and focused, SoftQuad’s uses and how the documentation will be information hierarchy. Critical to any XML presentation helped demystify some of the output. A well-developed CMS aids in application, information hierarchy defines issues surrounding XML. Jay’s explanations content repurposing and the data model in the relationships or rules for managing the increased our familiarity with the issues place can be leveraged to meet the client’s enterprise knowledge. Word processing files involved in implementing an XML needs. Print output can take the form of are flat, meaning that they possess no application and the benefits of using PDF or FOP (formatting objects processor), information hierarchy, whereas relational XMetaL as an authoring tool for postscript, or older FOSI/DSSL standards. In databases can contain a complex managing XML content. For more addition, clients must consider issues such hierarchical structure. Jay warned that the information about their products and as whether the data model is proprietary richer the hierarchy, the greater will be the services, visit their web site at and whether information needs to be resources required to maintain the content, www.softquad.com. archived. and the more complex the data model, the slower will be the XML conversion process. ✍

President’s Column Continued from page 1 professionally, creatively, and socially. I recall my first visits to the North Bay presidential duties with aplomb (now there’s chapter meetings, and the insights gained a word that you’ll probably never get to use and new friends made. There is an esprit de Writing for the Web in a technical document!). corps among our group that I highly value Continued from page 2 and look forward to joining in every Our chapter continues to grow in number month. and in spirit, reflecting both the continued Contact Information: www.infopros.com need for qualified technical communicators Much credit also goes to our local 6060 Sunrise Vista Drive, Ste 2180 among North Bay companies, and the academic and vocational institutions Citrus Heights, CA 95610 enthusiasm of the new converts to our (including Sonoma State University, Santa 916.725.5558; Fax: 916.726.8223 profession. I am particularly impressed with Rosa Junior College, and the Tech E-mail: those individuals among us who came to our Academy in Petaluma) for ramping up [email protected] meetings to research the possibility of their technical communication course [email protected] making a career change, liked what they programs to meet local needs and better heard and saw, and then took the brave steps serve our chapter members. to gain the necessary technical communication skills to make the change. In closing, I’d like to congratulate chapter ✍ member Kate Samsa for attaining the I like to think that our chapter meetings noble rank of STC Senior Member. have been inspirational to these folks, ✍

7 northbay news, may/june 2001

ASI Golden Gate software, Frances suggested training a th According to Frances, the pros of using Chapter’s 18 Annual voice recognition software include typist to enter marked-up entries or exploring ergonomic workstation Conference alleviating shoulder, wrist, and neck strain; increasing productivity; and leaving hands equipment. Sylvia Coates, Karin Arrigoni, and free for other tasks. The cons include voice Chris Ronhausen, ASI Golden Gate and throat strain, the need to speak very Sky Index Chapter slowly; misunderstood or misspoken words; http://www.sky-software.com the need for “keyed” editing; and On April 28, the Golden Gate Chapter of Kamm Schreiner of Sky Index announced interference from background noise. the American Society of Indexers held its the new Sky Index 6.0 version (available in annual Spring Conference at Fort Mason in June) and gave a demonstration of some of the new features, including the following: San Francisco. Approximately 30 ViaVoice participants saw demonstrations of three http://www.comdex.com 1. Ability to preview the index voice recognition (VR) programs— Frances demonstrated the Millennium 2. Un-deleting deleted records 3. Time stamping ViaVoice, VoiceXpress, and Dragon—and edition of ViaVoice, which sells for about how they are used with the three high-end $80 or $130 for an enhanced version. 4. Tracking of multiple indexers’ work on indexing programs—CINDEX, Sky Index, Unfortunately the enhanced version only an index and Macrex—, as well as with Microsoft works with Microsoft applications such as Word. Word and Excel. The enhanced version can be used with CINDEX by dictating into the software’s own word processor, SpeakPad.

ViaVoice has some shortcomings, including persistent insertion of spaces between characters, bolding of characters, and complex training of macros. ViaVoice requires both a major investment of time for voice training and upgraded computer equipment. Dragon with Cindex Many CINDEX users prefer Dragon Naturally Speaking. Using Dragon, users can dictate directly into CINDEX, or, as many CINDEX users prefer, speak into Dragon’s own word processor—essentially preparing a CINDEX data file—and then import the file into CINDEX. The advantage to importing a file into CINDEX is that fewer instructions need to be spoken, which speeds up the dictation process. Editing can be done by voice but is You don’t need to worry about these dragons...... with the right wizard, they’ll fulfill your merest whim. not recommended due to difficulties with cursor placement. CINDEX Alternatives to VR Software VoiceXpress http://www.indexres.com Though some indexers successfully use it, http://www.lhsl.com Frances Lennie introduced CINDEX and for many indexers VR software is not a Kamm demonstrated VoiceXpress 5.0 demonstrated ViaVoice. CINDEX operates viable option. As an alternative to using VR Standard Edition with Sky Index. While on either Windows or Macintosh platform. Continues ☞

8 northbay news, may/june 2001

VoiceXpress was easy to install, the There were several apparent differences evident that the entry input had the program was unable to automatically between Dragon and the other VR potential of being very efficient. adjust the microphone recording level on programs we had seen demonstrated the notebook computer Kamm was using. earlier. Dragon did not become confused by Pros and Cons of Dragon other voices and so background noise isn’t Gale cautioned that while VR programs are as much of a factor as with the other Kamm shared some of the same not for everyone, they are certainly viable programs. And Dragon has some frustrations with VR software expressed by for some indexers. Of all the VR programs, sophisticated scripting and macro Frances. He was particularly frustrated with Dragon seems to be the most accurate and capabilities but will only work with a having to repeat words with different easiest to train. There are fewer problems limited number of word processing inflections and varied tones of voice several with background noises. While in general programs. Also, Dragon seemed to work times before obtaining the desired result. indexers should take breaks from the very slowly with Word; a moderately Even after repeated efforts, the program computer at least every hour, when using adequate typist could input at a faster would frequently misinterpret the word Dragon, getting up every 20 to 30 minutes pace. and require physically keying in the edits. is recommended. It appears that using Dragon can be physically demanding even For Kamm, VoiceXpress’s features are very Macrex though it does protect the hands from good for the price. VoiceXpress allows the http://www.macrex.com additional stress. And while entering creation of personalized commands, which Gale Rhoades presented the latest version entries may go faster with Dragon, can help reduce the speaking required for of Macrex. A Windows application, Macrex particularly for the slower typist, there is some of the voice recognition tasks. Still, has maintained a DOS-type interface. additional time spent editing the index for Kamm was not able to create commands Rhoades demonstrated Macrex’s extensive any misunderstood entries. containing certain keyboard keys such as macro capabilities. Ctrl and Alt, and his overall observation was that using VoiceXpress would simply Conference Summary cost the average indexer too much time to Macrex with Dragon The conference closed with a panel be cost effective. Gale reviewed her experience with indexers discussion with Frances, Kamm, and Gale. using Dragon with Macrex. Some Macrex For anyone interested in VR programs, this conference was well worth their time. Dragon with Sky users have successfully worked with Dragon since 1995.Dragon can be used directly Frances Lennie, Kamm Schreiner, and Gale Kamm acknowledged that many Sky users with Macrex. Rhoades were well prepared, employ Dragon Naturally Speaking for knowledgeable, and ably demonstrated voice recognition. Kamm pointed out that Gale discussed the advantages for an three VR programs. They covered the pros VR programs require large amounts of indexer of working with Dragon. Dragon is and cons of using VR programs for memory to run; Dragon in particular particularly good for embedded indexing. indexing. requires 256 MB. In addition, successful Dragon makes it easy to use macros to transmission depends on the quality of the track the embedded codes throughout the Neither Frances nor Kamm could sound card installed in the user’s index. In addition, Dragon can speed up recommend ViaVoice and VoiceXpress. computer. the time spent entering entries for a slow However, Gale said that if an indexer were typist. In contrast to Word, Dragon worked to benefit from using a VR program, Dragon Naturally Speaking at a rather fast pace with Macrex. Gale did Dragon is probably the best program to use. http://www.dragonsys.com stress, like Kamm, that a good sound card Frances and Kamm agreed that Dragon is Ron Katuranis explained that Dragon’s and microphone are essential for an likely the best VR program available today parent company, L&H, is currently efficient indexing process. and is being used successfully with all experiencing some legal and financial three indexing programs. But all three difficulties. Unfortunately, no one is really Dragon does require some voice training in presenters agreed that the decision to use a able to predict how these problems may order to become efficient. Gale VR program is a very individual choice to affect the availability of Dragon in the demonstrated how to begin voice training be made only after careful considerations future. Ron demonstrated Dragon using with Dragon and she input a number of of all the issues. Microsoft Word. entries during the presentation. It was ✍

9 northbay news, may/june 2001

We meet on the third Thursday of each month

Our July Meeting Thursday, July 19, 2001

Topic: “When I Grow Up, I Want to Write API Docs” Presenter: James F. Bisso

Parker Compumotor 5500 Labath Drive Rohnert Park http://www.stc-northbay.org/

10