Assembling the People You Need, by Steven
Greffenius
President's Message, by Taryn Light
Reward Offered, by Denise Dennett
Benefits of Entering STC Competitions, by
Mary Vazzana
"True" Web Help, by Neil Perlin
Independent (but not Alone) with New Contracting SIG,
by Karen Giventer
XML for Technical Communicators, by
Anne Louiselle
Building Relationships with Developers,
by Anne Louiselle
End of the Year Event
Announcements and Activities
Chapter Membership Reports, by Zohra
Iqbal Mutabanna
Boston Broadside Staff
By Steven Greffenius
When you need to produce a technical document, you can rely on three types of resources. You can employ in-house staff, hire temporary staff through a contracting agency, or hire the services of a technical publishing firm. Let's compare cost, quality, and control of these three options.
From the standpoint of price, using in-house staff is an attractive option. They are already on the payroll, and they already have much of the training that they will need. Outsourcing the job requires adding a substantial chunk of money to your budget request. The budget item is visible and has to be justified, whereas assigning the job to people already on board is invisible to the manager who oversees the budget. If the people who take on the publication were hired for that kind of project or were idle anyway, then the company has made good use of its resources.
On the other side, a major writing project won't boost the morale of engineers or other staff who do not see documentation as part of what they were hired to do. If writing forces them to neglect other important work where they feel their talents are well used, then the hidden cost to the company can be rather high. In that case, outsourcing the project can make the final stages of product development more efficient and less aggravating.
When your company decides to produce a document, it is usually pretty late in the product development cycle. Customers want documentation with the shipped product, and they won't be happy if the instructions are missing. How can you produce a high-quality technical document—one that serves your customers well—on a tight deadline? This section examines the question of resources with the tradeoff between time and quality in mind.
Some managers look to agencies to help them assemble the resources that they need on short notice. Agencies can quickly send them candidates with the right skills. Later, they look at the quality of the talent they hired and wonder if they didn't pay too much.
The problem is not that agency writers cannot produce high-quality material. Many talented writers have worked with agencies. The quality problem arises because the agencies themselves use a "meat-market" model to place their offerings. They, too, are concerned with time. As a result, they generally do not know whether they have sent ground beef to McDonald's and their best filet to the Ritz, or the other way around. How does this problem look from the perspective of the project manager? Even if an agency looks attractive in the short term, the decision to hire staff there can cost time and money over the course of a project. The agency solves the immediate hiring problem, but this source of talent returns unreliable quality for a relatively high price. Why? For at least three reasons:
Of course, contracting agencies are here to stay. They serve some useful purposes for both writers and managers, and they have become well established in our trade. Most of all, they serve as a good backup when time is short. Yet both writers and project managers can easily let procrastination become a bad habit. If writers procrastinate in their marketing efforts and managers procrastinate in their hiring, then agencies become a routine fallback option. With foresight and plenty of direct contact, contract writers and project managers can develop solid business relations that result in high-quality work and less wasted time.
Project managers may feel most comfortable if the work that they supervise is conducted in-house. That makes for smooth and generally uninterrupted communication. Guidance, feedback, trouble reports, plans, work schedules, and inter-departmental notices can all flow back and forth seamlessly when writers and editors work on the premises. In addition, on-site work gives writers and editors direct access to the company's network, and helps avoid the version control problems that can arise when work is conducted off-site.
In light of all these advantages, one might want to know why a project manager would ever want to supervise work conducted off-site. Here are several reasons:
Many projects, of course, include a combination of on-site and off-site work. Often, a great deal of on-site time is required during the research phase at the beginning of a project, and during the publication phase at the end. The document development phase in the middle can be conducted on- or off-site. Writers and project managers can agree in advance on what arrangement will work best.
Here are some guidelines that we can derive from our analysis:
Steven Greffenius can be reached at sgreffenius@techniscribe.com.
By Taryn Light
First, a hearty "Thank you!"
This past year, Hans Fenstermacher, our immediate past president, hit a grand slam, drove in the winning runs, and brought us victory! Thank you, Hans, for leading us to the worldwide Chapter of Distinction award and raising the standards for the rest of us to follow. Thank you also to the many hard-working officers, council members, committee members, and volunteers who comprised the winning team. Without you, we would not be able to serve our members.
As your incoming chapter president, I feel like a Red Sox batter (and a rookie one at that) who just stepped up to the plate after Hans' grand slam! He's a tough act to follow. Thank goodness, Hans will continue on our Council in an advisory position as the Immediate Past President. The legacy of his leadership will continue.
It's a good thing that we don't have players with confusing names like these on our team! However, you still need a game program to know "who's who." Please put your e-hands together and welcome our new STC Boston Chapter Officers and Council members.
You already know a bit about this talented team from reading their biographies on our recent ballot. In the next issue of the Broadside, I will share more about each officer and council member and, hopefully, show you their photographs.
Looking ahead, we must create a vision that leads to action — one that brings about positive change. With this in mind, I set the following goals for the STC Boston Chapter:
If you have talents that will help us meet these goals, please let me know.
When I attended the STC Annual Conference in Nashville, TN, in May, I heard the following quote that sums up my goals for this year.
Vision without action is merely a dream
Action without vision just passes the time.
Vision with action can change the world.
—Joel Barker
Together, we can meet the goals of our vision, because the STC Boston Chapter is a chapter of action and together we can make our vision a reality!
Taryn Light is the president of the STC Boston Chapter. She can be reached at taryn.light@verizon.net.
By Denise Dennett
When you submit a technical document, technical art, or online communication project to an STC Competition, you always get something out of it. You might win an award. But even if you do not, you will get valuable feedback about the submission. The STC Competitions let you see how your work stacks up against your peers in the industry. Check out the Competitions Web page (http://www.stc-boston.org/competitions) to see the entries that won awards in the 2001 competitions. Wouldn't it be great to see your name on next year's winners list? Wouldn't your company enjoy the publicity of having their documentation known as award-winning?
The recognition and benefits of winning an STC award can last for years. First, you get the immediate benefit of proving to your management that you do great work. But imagine listing an STC award on your resume. Employers find it difficult to determine who can write and who cannot; an award from your peers (who are always your toughest critics) can really grab a hiring manager's attention.
Each year, the Boston and Northern New England chapters present awards at the Distinguished, Excellence, and Merit levels. One Best of Show winner per competition (publications, online communication, and art) will be selected. Winners of the Distinguished award qualify for entry in the STC International Competitions. Check the Competitions Web site to see a list of local entries that won international awards.
For the first time, we will be accepting submissions over the Web only. Fill out the submission form, and then follow the instructions on the form to submit your entries to the specific competition(s). Judging is completed in mid-November, so you should get feedback by early December.
You can find the entry requirements for each of the competition categories (online communications, technical art, and technical publications) on the Competitions page (http://www.stc-boston.org/competitions). The online submission forms and judges' registration forms should be available by August 1.
People who enter the STC Competitions submit their best efforts for that year, seeking recognition and feedback. By volunteering as a judge, you can review the best work in our areas. Judging is a great way to see what others are doing and to network with your peers.
You can enter the competitions, and you can judge the competitions. We ensure that your entry is assigned to another judging panel, so you do not have to worry about any conflict of interest. Plus, you will get the maximum benefit of having your work judged, and judging the best work of others.
The Online Communication judging will take place on November 2 at Hewlett-Packard (formerly Compaq) in Nashua, NH. We will send you the complete details when you register as a judge.
The Technical Art orientation and consensus judging will take place at Sun Microsystems in Burlington, MA. We are still working out the details, and will send you the necessary information when you register.
The Technical Publications orientation will take place on October 5 (location TBD), and consensus judging will take place on November 9 at Middlesex Community College in Bedford, MA. Complete details will be sent to you when you register.
To support competitions this year (and for many years to come), the Boston and Northern New England Chapters are developing a new Web-accessible database. We anticipate that entrants and judges use the Boston Chapter Web site to complete the entry forms and judging registration forms. This centralized database will make it easier for volunteers to coordinate all the entries and to assign them efficiently to the judges.
We expect the database online to start accepting entry and judging registration forms online by August 1. In July, we will extensively test the database, and we'll need your help. If you want to volunteer to test the database (which involves completing entry and registration forms online), send a message to stc_comp@yahoo.com. Because we want the database implementation to be as smooth as possible, we would like to have as many people test it with as many different Web browsers as possible.
For more information about the STC competitions, visit the Competitions page at http://stc-boston.org/competitions or contact one of these people:
Technical PublicationsDenise Dennett is the technical publications coordinator for the Boston/Northern New England STC Competitions 2002. She is a senior technical writer at SupplyWorks, Inc. in Bedford, MA.. Denise can be reached at denise_dennett@supplyworks.com.
By Mary Ellen Vazzana
Associate Editor: Mary Oliver Flebotte
If anyone asked me to state the most confusing and frustrating part of being a technical writer, then I would say that it is the subjective nature of presenting technical information. Structure of material, writing style, even font selection—what is right and what is wrong? If you're like me, you probably find yourself digging through style guides and information that was written in the past and praying that what you've selected makes both your editor and the software development team happy.
I have read several books on technical writing, most of which taught me how to be a more efficient writer. However, because our reading audiences are so diverse, accommodating their needs constantly challenges me to find new and inventive ways to present information. Therein lies the subjectivity. And this is what initially attracted me to the STC Competition.
The judges in the STC Competition are our industry peers, many of whom have numerous years of experience in technical communication. When we enter work in the competition, the judges are actually acting as peer reviewers of our efforts. It's a great way to get positive reinforcement, constructive criticism, and even new ideas.
Material entered in the competition is judged on its own merit, against a set of well-honed evaluation criteria. The STC judges are all trained in advance of the competition to be sure they thoroughly understand the judging process, how to use the criteria and forms, and how to provide comments that are most useful to the entrant. In the publication's competition, the judges first evaluate their sets of entries independently and later meet with fellow judges to come to a consensus on the entries. This process adds the extra benefit of providing entrants with several points of view. Not only do they receive individual comments, but the entrants also receive the collective thoughts of the consensus team.
Whether or not a particular piece officially wins an award, every competition entrant still comes out a winner. I found the local and international STC judges' feedback to be extremely valuable. I make it a point to evaluate their feedback closely and share the information with my co-workers. The feedback enables me to improve my work, grow as a technical writer, and best of all, provide better technical documentation to my readers.
In the end, everybody wins.
Mary Ellen Vazzana is a technical writer at AutoDesk, Inc. Mary Oliver Flebotte is the NNE Chapter Vice President and a member of the joint Boston/NNE STC Competition Committee. Mary is a software technical writer at BAE SYSTEMS.
By Neil Perlin
Editor's Note: Part 1 of this article, "Online Help Today" (http://www.stc-boston.org/broadside/05_2002/v59_no5_perlin.shtml), appeared in the May/June issue of the Broadside.
As help becomes increasingly Web-like, a group has emerged in the help development community to argue for replacing help-authoring tools (HATs) with true Web-authoring tools, primarily Dreamweaver. This movement has grown for over a year and signifies another major break from the WinHelp/HAT standard. Some of the arguments:
Why move to Dreamweaver?
Why stay with a HAT?
Tools like Dreamweaver are complex. Many Dreamweaver-based development groups suggest having an in-house techie, something that smaller companies may not find feasible. The HATs are limited but simpler, and offer a largely all-in-one development environment for people whose focus is content creation rather than coding.
The Dreamweaver approach seems to lead developers to abandon a table of contents and index in favor of full-text search. This approach puts a Webbish slant on the presentation of online information. However, the standard table of contents and index are often appropriate and should not be abandoned just because of a move to a new format. HATs are designed to help developers create standard navigational features such as tables of contents and indexes. Developers can then include those features and leave their use up to the users.
All modern Web development tools claim to be WYSIWYG, but the best that you can realistically hope for is WYSIAWYG (What You See Is Almost What You Get—thanks to John Garison). This is most likely a draw between the HATs on the one hand and Dreamweaver on the other.
The last few years have seen major changes in the HAT market. Various tools have come and gone, but the status of the major tools is as follows:
eHelp's RoboHelp (http://www.ehelp.com), now up to version 2002, has solidified its position as the market leader. (eHelp changed its name from Blue Sky Software.). One of the biggest changes in RoboHelp is the emergence of the Enterprise module, which offers natural language recognition, usage logging and report generation, and multimodule project merging. This latter feature appears to be a move by eHelp to meet competition from Dreamweaver in the help authoring market.
The HAT market pioneer, Wextech (http://www.wextech.com), sold Doc-To-Help to ComponentOne (http://www.componentone.com), which has rewritten and rereleased it. Wextech itself has left the HAT market to focus on speech recognition via its AnswerWorks product.
Forefront, formerly number two in the market after eHelp, sold ForeHelp to ComponentOne and closed in January. Some of the ForeHelp technology, including its cross-platform, cross-browser InterHelp format that competed with eHelp's WebHelp, will supposedly be integrated into a later version of Doc-To-Help. The rest of ForeHelp will disappear.
The Dreamweaver approach is supported by help templates from Deva (http://www.devahelp.com), which let developers add the interface and some of the navigational features that are associated with traditional help.
Where is the industry going? The drift away from the WinHelp "model" continues. Different vendors, even different Microsoft groups, use different help styles, and you'll find still more styles used in Web-based applications. Many companies still use the WinHelp model because of its simplicity and predictability, but that is no longer a given.
Three interrelated trends have appeared:
One issue remains undefined at this time: In early 2001, Microsoft announced that Help 2.0, the next release of HTML Help, would appear in 2002. In February 2002, Microsoft announced a limited release via Visual Studio .NET but warned that the general release had been delayed until 2003 at the earliest, apparently to align it with .NET. There will be a temptation to make jokes about Microsoft's release schedule, but that schedule now appears to be driven by larger strategic issues.
The good old single-standard days are gone. We now have a variety of options for presenting online help, and the problem is to avoid picking the coolest option in favor of the most effective one. For 45 percent of the market, WinHelp is that choice. Yet, in the long run, WinHelp is a dead end. In order to move beyond it and react to continuing technical changes, help developers are going to have to do two things:
In short, we're continuing to turn into quasi-programmers.
Neil Perlin has 23 years experience in technical communication, with 17 in training, consulting, and development for various types of online documentation and tools including WinHelp, HTML Help, CE Help, JavaHelp, RoboHelp, and some now known only in legend. Neil writes about online documentation and speaks frequently before the STC and other professional groups. He is a senior member of the Boston chapter of the STC. Neil also started and runs the Beyond the Bleeding Edge substem at the STC's annual conferences. He provides training, consulting, and development for various forms of online material, XML, and the mobile wireless Web through Hyper/Word Services of Tewksbury, MA. He can be reached at nperlin@concentric.net or http://www.hyperword.com.
By Karen Giventer
Question: What's the most popular SIG in STC?
Answer: The Consulting and Independent Contracting (CIC) SIG.
This fact should come as no surprise, considering the many technical writers who are either contracting now or eyeing contracting as an attractive career choice. Layoffs during recent months have also caused skyrocketing growth in the ranks of contractors.Now the Boston Chapter of STC has its own local CIC SIG. The fledgling group is already going strong, and at the first meeting the group outlined its goals, including:
Everyone who has an interest in contracting is welcome: experienced contractors, aspiring contractors, agents, students, full-timers, and in-betweeners. Your active participation will make this a strong SIG.
To keep current on events and meetings, see the Consulting and Independent Contracting SIG page in the Special Interest Groups section of the Boston Chapter Web site (http://www.stc-boston.org/sigs/contractors.shtml). To receive notices of future meetings, join the CIC SIG Yahoo group, CICTalk, by sending an e-mail to CICTalk-subscribe@yahoogroups.com. No subject or message is necessary.
Karen Giventer is a contract technical writer and enthusiastic member of the Consulting and Independent Contracting (CIC) SIG. She can be reached at kkgg123@hotmail.com.
By Anne Louiselle
|
|
| Neil Perlin explains XML concepts. | |
| Photo by Anne Louiselle |
Perlin explained that browsers will display XHTML with no apparent differences on the surface, but that XML appears to be the wave of the future. Why?
XML is important because it avoids the weaknesses of HTML. XML separates form from content, allowing custom tags, enforcement of syntax, and code that can be reused, much as a cascading style sheet is now used with HTML. This is crucial for single-sourcing.
What is single-sourcing? Perlin defines single-sourcing as creating content once and using it for help, hard copy, and a Web site. "If you are using RoboHelp or ForeHelp to create online and hard-copy communications or FrameMaker and WebWorks to create hard-copy and online communications, you are already single-sourcing now, just not according to the hot definition that involves XML. Reuse is the common thread."
 |
|
| Attendees Helen Shaw and Heather Lane | |
| Photo by Anne Louiselle |
To determine whether you need to adopt single-sourcing, Perlin suggests that you consider the following:
 |
|
| Attendees David Kaye, Alex Cherniak, and Kathy Pappas | |
| Photo by Anne Louiselle |
"The more your answers tend toward high-volume, high-complexity, the more appropriate XML begins to look. Avoid designing solely for today," Perlin said.
For more information on XML, Perlin recommended the following resources:
 |
|
| Attendees Jeffrey Dyke and Allison Snow | |
| Photo by Anne Louiselle |
Neil Perlin provides training, consulting, and development for various forms of online material, XML, and the mobile wireless Web through Hyper/Word Services of Tewksbury, MA. He has 23 years of experience in technical communication. For more information on upcoming workshops, visit http://www.hyperword.com.
Editor's Note: For more information about Neil's work, see "Online Help Today" in the May/June 2002 issue of the Boston Broadside (http://www.stc-boston.org/broadside/05_2002/v59_no5_perlin.shtml) and "True Web Help" in the current issue (http://www.stc-boston.org/broadside/07_2002/v59_no6_perlin.shtml).
Anne Louiselle has been a member of STC since 1997. She can be reached at alouiselle@attbi.com.
By Anne Louiselle
 |
|
| Joe Dumas | |
| Photo by Anne Louiselle |
At the joint meeting with the Usability Professionals Association (UPA) and the Boston Chapter of the Society for Technical Communication on Wednesday, April 17, 2002, Dumas explained how relationships could be developed and enhanced.
"Methods of evaluation differ, but they provide opportunities to work together with developers. Making the relationship work is critical," said Dumas. "Trust, mutual respect, and bonding through work can help build a good relationship. Trust means providing consistent support so that there are no surprises. Mutual respect means sharing objectives and working as team players. Bonding through work occurs when people work through adversity and share in the hard work." Dumas provided three methods of usability evaluation and explained the opportunities that they provide to develop the relationship.
For example, in usability testing, activities include conducting a pilot session and negotiating changes to tasks and scenarios. "Be sure to set expectations. There will be some chaos. Explain that you cannot get it right the first time. Explain that not all problems are the same. Make these opportunities to foster trust and mutual respect," said Dumas.
 |
|
| Attendees Daniela Gran, Michael Flynn, Pamela Schmitt | |
| Photo by Anne Louiselle |
In expert review, the usability specialists work with developers to set objectives, a user profile, and a common set of tasks. The usability specialists independently inspect the user interface, perform all tasks, work through all screens, and complete problem identification sheets. The usability specialists convene, form a consensus, prepare a presentation or report that lists the problems by severity, and sometimes propose solutions.
"Foster trust by deciding what is most important and consider leaving the rest out. Foster mutual respect by reviewing all comments for emphasis and tone and consider separate packaging of guideline violations. Don't ignore the guideline violations, but let the developers know that they are there and the five most important things that they need to do," suggested Dumas.
 |
|
| Attendees Cynthia Whitty, Phyllis Beal, Nicole Cerimeli | |
| Photo by Anne Louiselle |
In a usability walk-through, usability specialists and developers walk through tasks step-by-step. They consider what the user will most likely do, and they locate problem areas. "This provides an opportunity for the developers to see how the usability specialists uncover issues and set priorities. They identify problems together and discuss the scope and severity of problems. This method has great potential to build trust in the relationship," said Dumas.
"Your relationship with developers counts. Ask yourself, are we good colleagues? Do we provide support when we bring bad news? The methods of usability evaluation uncover problems. Often, that's bad news. Ask yourself, did we set expectations with developers? The way you deal with developers is critical to the success of usability," said Dumas.
 |
|
| Attendees Michael Ledoux, Cynthia Toryu, Julie Rodriguez | |
| Photo by Anne Louiselle |
Joe Dumas has a PhD in Cognitive Psychology and over 20 years of experience as a usability professional. He is a principal usability engineer at Oracle Corp. and has been a consultant on usability issues to many of the high-tech industry leaders, including Microsoft, Digital-Compaq, Lotus, Apple, Hewlett-Packard, Motorola, Kodak and the New York Stock Exchange. He is the author of Designing User Interfaces for Software. Dumas is an adjunct professor at Bentley College and teaches in the graduate program in Human Factors in Information Design.
Attendees described the program as an excellent presentation. One commented that "Joe's wisdom and maturity are particularly impressive." Another commented that there was "good emphasis on the importance of relationship building" and "good grounding on the different usability methods." For more information on the programs of the Boston Chapter of STC, visit the chapter's Programs page (http://www.stc-boston.org/programs/programs.shtml).
Anne Louiselle has been a member of STC since 1997. She can be reached at alouiselle@attbi.com.
 |
|
| Photo by Marguerite Krupp |
STC members cruised the Boston Harbor at the end of the year event on June 11. A list of award winners and more photos will appear in the September/October issue of the Boston Broadside.
View the End of the Year Event photo gallery.
Want to network with others in the field? Looking for answers about how other practitioners and educators have solved technical communications problems? Interested in specialized tutorials?
Come to the Association of Computing Machinery (ACM) SIGDOC conference October 20-23 in Toronto, Ontario, Canada, at the Toronto Downtown Hilton. For details, see our Web site at http://www.acm.org/sigdoc and click on the conference link.
STC's 49th Annual Conference was a great success! Attendees were delighted at the choice of technical and informative sessions, and they showed great enthusiasm for the technical communication profession.
The Conference marks the end of my three-year term as Director-Sponsor of Region 1. I met with most all chapters in the region at least once. I shared your successes and awards. I often sat and talked with you about chapter difficulties, and we worked out strategies to deal with them. You were all great and very dedicated to STC.
Please welcome your new Director-Sponsor, Jonathan Baker. I'm sure that he will do a wonderful job. You can reach him at jbaker2525@earthlink.net.
Thank you for being a part of the best job I have ever had!
Cheers,
Kitty
Compiled by Zohra Iqbal Mutabanna
Current membership: Boston: 967; STC: 19,052
| New Members: 14 | Reinstated Members: 14 | Members transferring in: 1 |
| Richard A. Benedict | Nancy Allison | Zev Frutkoff |
| Linda S. Cameron | Mabray C. Andrews | |
| Mary Jane DeAngelis | John P. Burger | |
| Michael A. DiBattista | Gwyneth C. Catlin | |
| Lisa A. Goodrich | James P. McDermott | |
| Amy Kerr | Christine F. Monteiro | |
| Stuart Kiang | Kenneth C. Ogle | |
| Martin J. King | Patricia A. Robertson | |
| Beth Paddock | David N. Skolnick | |
| Maryellen S. Rousseau | John S. Southworth | |
| Joseph N. Srednicki | Joan M. Stantial | |
| Kristen M. Sutton | Anita E. Tsiagras | |
| Candace L. Van Auken | Jane E. Varkonyi | |
| Kate E. Walker | Wangeci Wamunyu |
Daphna Edgar (dnahama@ivillage.com)
Audrey Borus (rborus@rcn.com)
Christine Jacobs (christine.jacobs@oracle.com)
David Levitt (dlevitt@erols.com)
Cheryl Magadieu (cmagadieu@attbi.com)
Patricia McLaughlin (PMclaughlin@mccrackenfs.com)
Margie Gooding (MargeAtLarge@hotmail.com)
Cheryl Magadieu (cmagadieu@attbi.com)
Christina Rothwell (crothwell15@yahoo.com)
Rich Feitelberg (webmaster@stc-boston.org)
Zohra Iqbal Mutabanna (zo@mutabanna.com)