Features

(c)2009 Goeff Hart. Goeff is an STC Fellow and member of the STC-Montreal Chapter. This article was originally published in the Spring 2009 issue of the ISTC Communicator, and is reprinted with permission.

Publishing long documents from a topic-based perspective

MadCap’s Blaze software is a long-document solution designed to compete with Framemaker—and (to a lesser extent) with Word, which isn’t really optimal for long documents. In this review, I’ll give you a basic idea of how version 1.3 of Blaze differs from its competitors. For a more detailed review, please see my longer article on the techwr-l Web site.

What’s different?

Most of the software we use for writing is based on individual documents: in the center of the screen, there’s a document window, surrounded by a menu bar at the top and various floating toolbars or palettes. But it’s the document that is at the center of this model. If you’ve written online help or created a Web page, you’ve seen a different metaphor: the focus is on an “organizer” that displays the collection of information you’ll be working with, a central area that displays a subset of that information while you work with it, and miscellaneous floating toolbars and palettes. But it’s the organizer and the collection of information it represents that lie at the heart of this interface. Blaze refers to this collection as a “project”.

Although Blaze is designed for the production of long publications, not online help or Web pages, it relies on the latter interface. The Blaze workspace comprises the following main elements:

• At the left, you’ll see Project Organizer and Content Explorer windows that (respectively) show the project’s contents (all resources associated with the project) and a subset of those resources, such as the list of topics or graphics.
• At the center, you’ll see the information you’ve chosen to work on, such as a single topic selected from the Content Explorer.
• Floating but dockable palettes for applying styles, adding index entries, and so on, as well as support tools such as the menu bar and help window. All windows and palettes can be repositioned and resized, and you can save collections of window and palette layouts for future reuse.

All this functionality takes up considerable space. You’ll be more comfortable with a large widescreen display than a square monitor; even my 21-inch square-screen CRT wasn’t large enough to display everything at an adequate size, and my 21-inch widescreen LCD, though adequate, was more cramped than I would have liked.

Topics versus documents or stories

Blaze’s approach resembles managing a small Web site or a collection of Help topics more than it resembles working with a collection of documents or the “stories” used by desktop publishing software such as InDesign. The difference is subtle, but understanding it is crucial to understanding how Blaze is different. Blaze is topic-based, which means that you build projects from discrete chunks of information that can be mixed and matched and assembled into larger publications. Dividing a large book created in Word or Framemaker into individual chapters, with one file per chapter, is a step in this direction, but Blaze encourages and supports a far more granular approach. (Here, “granular” means the ability to break things into grains of varying sizes.)

The advantage of this approach is that it lets you create collections of information ranging in size from the largest elements (individual topics) to elements as tiny as one or two sentences (such as a standard warning message) or even phrases (such as your company’s name). In some ways, the approach is like playing with a large box of Lego, except that the building blocks in Blaze are defined once and then reused. In fact, Blaze is designed from the ground up to let you easily reuse information: instead of creating a separate copy of each piece of information for each publication that contains it, you create that information only once and then include it “by reference”; only a single original copy of the information ever exists, and updating that version automatically updates all publications that contain it. For example, a standard company-wide “how do I reach tech support?” page could be a midsized element of your project, whereas your company name itself could be a smallish element. Should your company be acquired by a larger company, your tech support page and company name would both change, but you would only need to update the original information once; all parts of your projects and all projects would be automatically updated to use the new information. You can fake this with other software, particularly if it offers a “library” feature, but Blaze fully embraces this principle of reuse. In effect, it’s a form of single-sourcing, though you can’t create online Help with Blaze. (You can, however, open a Blaze project in Flare and create Help files that way.)

Building publications

Blaze lets you create multiple publications, such as student and trainer versions of a training guide, from a single project. To do so, you create outlines, which are like shopping lists that define what elements should appear in each publication as well as their order. You can also create conditional tags, such as “student” and “teacher”, that specify which elements should only appear in certain publications. Blaze also provides “templates” that define broad collections of project settings that go far beyond simple gatherings of page layouts and text styles.

Blaze provides familiar tools for defining standard page layouts with recurring features such as running headers and page numbers that you can apply to each topic in a project. You define each page’s structure using “frames”, which are containers that hold subsets of the page’s contents. Typical frames include the running headers and footers that appear on every page, the body text frame that holds the majority of a page’s contents, and sidebars. You can also use “text boxes” similar to those provided by Word for exceptional information that doesn’t fit within the standard layout’s frames. There are many nice page design features, such as the ability to automatically align a page’s components and the ability to mirror pages to instantly create matching facing pages. Page layouts stored in a project’s Resources section are available for use in any topic in the project.

Blaze provides style sheets that store the formats for entire paragraphs (paragraph styles) or subsets of paragraphs (character styles), and you can define multiple style sheets per project. For example, you could create separate stylesheets for the e-Book and print versions of a project. All the standard text formatting options (typeface and type size, indentations and spacing, bullets and numbering) are available. Blaze isn’t yet in the league of InDesign, but you can certainly set credible-looking and highly legible type once you learn where all the settings are hidden, and can change your typography quickly just by changing the style sheet.

Writing, revising, and publishing

Blaze provides a basic but effective text editor. It isn’t nearly as powerful as Word, but it gets the job done. The table editor is good, with nice features such as the ability to define a collection of styles for an entire table. Blaze’s “snippets”, predefined text shortcuts, are more powerful than Word’s autotext and similar to Dreamweaver’s library items: if you create standard snippets such as a copyright statement or a standard warning message, editing the original snippet automatically updates all copies of that snippet in a project. There are powerful features for creating numbered lists and nested lists that update correctly when you add new information in mid-list—unlike those in Word.

If you don’t like the text editor, you can do most of your writing and revision in your favourite word processor or in Framemaker. If you save these files in Word’s .doc or .xml formats, or create Framemaker files, Blaze can import these files for subsequent management and publishing, and can use the updated versions of these files if you continue to modify them outside Blaze. Blaze’s X-Edit family of products provides powerful reviewing tools that resemble Word’s revision tracking and commenting features. The basic X-Edit Reviewer software is free for downloading, and you can purchase more powerful versions that offer additional features. The basic approach is similar to Adobe’s InDesign plus InCopy combination, but less expensive.

Blaze’s underlying document structure is XML, a tagging language similar to the HTML used to create Web pages. Although the XML editor used for writing and revising content shows you the XML tags for each chunk of text, they’re off to the sides, for reference only, and you work in “what you see is what you get” mode, so you can ignore the tags until you need them. (XML geeks will be pleased to learn that Blaze provides basic support for DITA, and MadCap is improving this support.) XML lends itself naturally to Blaze’s granular, topic-based approach, because XML defines a topic’s elements based on function (such as “title”), not format.

Graphics handling is simple and flexible, and you can collect all your graphics in the project’s Resources folder rather than inserting multiple copies in multiple files. Each image is then available for use anywhere, and when you update it, all topics that contain the graphic will be updated automatically to use the new version.

Blaze can automatically generate tables of contents (TOCs) for headings (both for a topic and for the overall publication), figures (graphics), and tables, as well as indexes and several cross-reference formats. The tools vary in their sophistication and maturity, but are all generally capable, if not as refined as their equivalents in Word and InDesign. Unfortunately, Blaze lacks scripting tools or macros; you’ll need a third-party tool such as MacroExpress to automate repetitive actions.

Once you’ve gathered all your information, you can define “targets” that combine the subset of the project you want to publish with your choice of style sheet and output format (PDF, Microsoft’s XPS, XHTML, Word, or Framemaker). The final step is to “build” each target, which is Blaze jargon for compiling the target’s contents into the final product. Once you finish building a target, you can issue a simple command to publish the project and send the output files to a network directory or a destination such as a Web site. The original source files used to create that output remain safely in Blaze: the published output contains only what is necessary for the audience to use the file on their computer.

Miscellaneous points

Blaze makes good use of embedded (“dynamic”) help that changes to reflect your actions and provide orientation (what does this dialog do?) or details when you select an option (what does this option do?). If you find that this gets in your way, you can use conventional context-sensitive help instead. There’s no printed documentation, but comprehensive, well-written PDF files are available, including a “Getting Started” manual that was sufficiently detailed that I could learn the software well enough to create a newsletter while I was writing this review. There’s no formal tutorial to walk you through the process of publishing a collection of sample files, so if you don’t like learning software on your own, you may need to obtain basic training from MadCap.

Should Adobe worry?

Blaze is a sophisticated, complex, powerful program that will take time to master. The payoff for that effort will be an ability to create a large family of related documents of varying length and complexity from a single collection of information, which is something you’d be hard-pressed to achieve with document- or story-based software. Moreover, it makes the task of updating members of that family easier than in other programs because modifying the original elements will ensure that all instances of those elements will be updated throughout the family.

Blaze has rough edges, and isn’t as intuitive as Word or InDesign. But even in its current state of development, it’s an excellent solution that will only improve as it matures. I wouldn’t sell my Adobe stock just yet, but were I Adobe, I’d be watching over my shoulder from now on.

submitted by Elaine Lanni
DocTrain East, Oct 29 – Nov 1, 2008 – Susan Burton, STC.
“The Changing Face of TechComm and the Society for Technical Communication”

Susan Burton, the executive director of the STC, was quite the dynamic speaker. She began by explaining that, although she’s not very technical herself, she appreciates that technical writers are out there to assist those who are technically challenged.

While in Kampala, Uganda, a few years ago, working for a nonprofit, she took the time to sit down with a homeless man who had a regular spot outside the gates of her hotel. He shared his history with her. Orphaned at a young age, he was forced to quit school because he could not afford the tuition. However, he proudly exclaimed to her that he had managed to learn how to use a computer — by having only a manual to read!

Shortly after becoming the director of STC, Susan discovered that the deadline to change an official “job description” for the US government’s Bureau of Labor had recently expired. With the assistance of a friend with government experience, she succeeded in acquiring an extension and began her work to redefine the profession of Technical Writer. Part of this effort involved consulting with the European Union. In doing so she learned about the German association, Tekom, that has 50,000 members and oversees the technical writing profession in that country. By law German companies are required to have a prescribed number of technical writers. This ensures consistency in documentation and accuracy, thus reducing risk where consumer safety is involved.

As a result of Susan’s efforts, the US Bureau of Labor has added safety implications to this job description and moved it out of a grouping that included journalists, weathermen and poets! They are considering putting us into a classification that is a new field. Here’s the current definition and the proposed definition.

Current definition of Technical Writer: Write technical materials, such as equipment manuals, appendices, or operating and maintenance instructions. May assist in layout work.

Recommended Definition: Develop and design instructional and informational tools needed to assure safe, easy, proper and complete use of technical goods and services. Combine multi-media knowledge and strong communication skills with technical expertise to educate across the entire spectrum of users’ abilities, technical experience, and visual and auditory capabilities.

This effort is just one of the 5 strategic goals of the STC. Here’s a synopsis of the other four.

• Communicate the Value. This is done through the STC publications and website.

• Improve the Practice. Through the annual STC conferences, our society provides an opportunity to network and learn. The upcoming STC Summit is in Atlanta, GA, May 3-6, 2009. There will be more than 100 sessions organized in seven tracks, and certification programs will be available. Additionally, we should all take advantage of STC’s live web seminars that are only $79 per site – not per person!

• Expand Our Partnerships. The STC has formed partnerships with numerous organizations such as The Content Wrangler, INTECOM, WritersUA, Writing Assistance and more.

• Ensure the Viability of the Organization. Says John Hedtke, STC Fellow, “Active Membership in STC is your best insurance policy against unemployment.” Some benefits of STC membership include a 14-day advance look at new job postings online, access to salary databases, and discounts on software purchases.

Thanks to free tickets provided by Scott Abel, The Content Wrangler, Elaine was able to attend Documentation and Training (DocTrain) East. She submitted two reports on the event.

Funny that sunglasses were the first item on my “to pack” list as I prepared to drive the 371 miles from Macedon, NY to Burlington, Massachusetts. It rained for about 360 of those miles! Headed to DocTrain East in Burlington, MA, from Oct 29 – Nov 1, 2008, I was looking forward to mingling with others in my field and learning about the latest technology.

In addition to two days of promising seminars, I had the opportunity to receive hands-on training for the software that I use daily at my job. A platinum sponsor, Author-it provided two full days of workshops as well as demonstrations of new features and a peek at functionality on the horizon.

Day 1 included 6 hours of Author-it training by an Kendra Carter, an engaging professional trainer who has been with Author-it since its inception in 2001. We were a varied group, consisting of users, prospective buyers who were evaluating content management systems, to a reseller, and a publisher who translated documentation using Author-it for global markets.

Meanwhile, other conference attendees had their choice of MadCap Flare presentations, Adobe FrameMaker training, and a session on publishing with Xmetal and DITA, just to name a few.

Day 2 began early with keynote speaker, Albert Chu. Chu is VP of Marketing & Alliances for Access™, the “world’s leading provider of software solutions for mobile and for beyond the PC.” He displayed several graphs that illustrated how the Japanese, and a number of developing countries, use their cell phones very differently than we do in this country. They access the internet via mobile devices more than twice as often as we do. He gave us a view into what may soon become the norm for global cell phone users – not just making calls and accessing the internet, but watching TV, paying for purchases, and zipping through the highway tollboths with a flash of our phones. (Can you say 3G and 4G?)

Random thought from keynote on advancing technology: You now have another reason to take care of yourself and live a long life! Every minute 13 hours of YouTube video are uploaded. To watch all of the video already posted will take you 412 years!

Tuesday evening was spent in the vendor ballroom where a bar was set up and tasty hors d’oeuvres were passed while folks and vendors mingled. I met a number of STC members from the midwest and we exchanged stories and challenges of our chapters. Their membership is so spread out that they have held program meetings online – and yearly they strive to find a locale for their conference that is within an hour’s drive for everyone.

The remainder of day two and day three offered a plethora of seminar choices. Out of 39 possible sessions, I noted that seven had DITA in the title. No wait, there were eight; one session left “DITA” out of the title and description. Ok, I know what DITA stands for (Darwin Information Typing Architecture) – and that it’s open source, and appeals to publishers who want XML-based solutions. Don’t know too much more about it, nor do I think that it’s the answer for everyone’s documentation needs. I shall stop here, lest I take on the label of “DITA hater,” as one fellow from the audience did. He expressed to the presenter that he’s “heard a lot about it over the last five years, but doesn’t know anyone who is using it.” Hmm, I see a need for a more detailed presentation, such as a detailed use case.

The common thread among the sessions was content reuse and its value in effecting consistency in outputs. If departments can share a content management system, the user manual’s procedure will be the same as the training material will be the same as the customer support department’s reference material. “When architected well, this happens seamlessly.”

To learn about “Content Convergence: Trends in the Creation, Production, and Maintenance of Technical Content,” I attended a presentation by Rahel Anne Bailie. She provided a real-life example of what can go wrong if you don’t reuse content. A US company produced a wasp spray that had varying instructions for use – depending if you were looking at the paper instructions or the can itself. Sure enough someone followed the incorrect instructions and was injured. The fact that the directions available to consumers was inconsistent fueled the lawsuit. Maybe it’s better to be consistent – even if you’re incorrectly consistent!

Rahel demonstrated a great example of content convergence in the web site called “Tripit.” Here you can have your travel information collected by simply sending them your confirming emails (for flights, hotel reservations, car rentals) to produce a personalized itinerary. Connect it to your Facebook or LinkedIn account and find out if your best friend Sally Ann may be in Vegas when you are!

A seminar of note for me was led by Char James-Tanney. Char owns a web site that provides assistance to anyone wanting to compare help authoring tools. She invites vendors to provide information on their software, which is then available for a customized comparison that the user configures from her site. Check it out if you’re so inclined. HAT-Matrix.com

To brush up on method of testing technical documentation I met Roy Jacobsen who presented “Document Testing: The Missing Step in Creating Effective Documents.” How many of us are so pressured to get documentation out the door that we don’t test it the way that it should be? He discussed the value in testing as well as four methods: prototype, focus group, usability and control studies testing.

One track that I didn’t visit, but seemed to have been covered thoroughly, was Localization and Translation. These sessions covered topics about effectively reaching and communicating with foreign markets, as well as translating user documentation.

Visit for more details on these presentations.

All in all this was a very worthwhile conference for me, and the Marriott was a great venue. The food was excellent and the staff was very professional. Scott Able took a poll after the last session to see if everyone was happy with the Marriott. The answer was positive, so most likely DocTrain East will return to Burlington, MA in 2009! Thank you to The Content Wrangler, his helpful and gracious staff and all the sponsors and speakers for making this event so enjoyable!

DocTrain East is one of several conferences every year devoted to content management and technical communication.

APEX 2008 NOW OPEN FOR ENTRIES

The 20th Annual APEX AWARDS FOR PUBLICATION EXCELLENCE is now accepting entries for APEX 2008 (Entry deadline: MARCH 17, 2008). The APEX AWARDS recognize excellence in graphic design, editorial content and overall communications effectiveness. Communicators can choose from 110 different categories under 11 headings, including:

# Newsletters,
# Magazines and journals,
# Newspapers,
# Annual reports,
# Brochures, manuals and reports,
# Electronic and video publications,
# Web and intranet sites,
# Campaigns, programs and plans,
# Writing,
# Design and illustration, and
# One-of-a-Kind publications.

For a list of new and revised categories, see the Apex Awards web site.

The competition’s entry deadline (postmark) is MARCH 17, 2008.

APEX is sponsored by the editors of WRITING THAT WORKS, a newsletter for writing, editing and communications professionals. The contest is open to corporate, nonprofit, freelance and agency communicators. Entrants do not have to be WRITING THAT WORKS subscribers. Entry fees are $69 per entry for WRITING THAT WORKS subscribers; $89 per entry for non-subscribers.

CALL FOR ENTRIES information, brochure and entry form are posted at
http://www.ApexAwards.com/apexawards.htm.

To download the APEX Call for Entries brochure, go to:
http://www.ApexAwards.com/apex_broch.pdf..

Just need the APEX Entry Form? Go to:
http://www.ApexAwards.com/apex_entry_form.pdf.
You can fill out the PDF Easy Entry Form right on your computer screen. (No need to find a typewriter or fill out the form by hand.) Then just mail it with your entries and payment.

Also see the APEX FAQ page for tips and advice on entering, at
http://www.ApexAwards.com/apex2008faqs.htm.