Proof Sheet

Are you a technical illustrator? Graphic designer? Interactive media designer?

bLog-oMotives: Calls for entries: Upcoming design competition deadlines.

Can’t get to the Summit this year? You can still get a taste of it here at the Proof Sheet. I’ll be reviewing the sessions I attend, Rochester Chapter member Beth Noble will be contributing at least one session review, and I hope to convince a few other attendees from other chapters to do the same.

Look for today’s session reviews:
Summit Keynote (David Pogue)
Accessibility SIG networking lunch
Documentation with Blogs, Wikis, and Online Communities
Selling Yourself and Your Skills
Social Networking
STC Annual Meeting
Communities Reception

(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.

(adapted from material David posted to the discussion list of the STC Consulting and Independent Contracting SIG; used with permission)

Your local Chamber of Commerce is an excellent resource, whether you’re looking for a full-time position or a freelance project. In a large metropolitan region there may a number of them, and they are often called by different names, depending on the city or town. Find yours by searching the US Chamber of Commerce directory search page.

All Chambers have directories of their members, because they act as free advertising, and many members prefer to do business with other Chamber members. Many of these local directories are available to the public for free. Others are closed directories, available to members only. The contact information is always kept current since this is the information the Chamber uses to maintain communication with the member companies. In my experience, the information is about as close to 100% accurate as it is possible to get. I did a mailing to 350 companies in our area and I did not get even one of them back. Every one of them was delivered! You will not get that sort of result with a purchased mailing list.

The contacts tend to be senior executives and usually include phone numbers with extensions. Many times you will find a listing for something like the “J. R. Smith Company” and the contact will be “James R. Smith.” This type of information is golden.

Please be aware a company may be listed in more than one category or with two or more Chambers in an area. It is very helpful to keep all contact information as a master list in a Word document. This allows you to use the Find feature to check if you already have that company’s information. I just did a copy/paste and made a few edits to clean up the data. Keep track of your contacts using this document.

Medium-sized and smaller companies may be a better target than large corporations. Fortune 500 execs are managing businesses that are so large they do not have time to think about the small stuff. To them you are small stuff. With a smaller company, you will often get to talk to the person who owns the company instead of being screened out by a gatekeeper. Execs in medium/small companies tend to be more aware of the local business climate than their corporate counterparts are, and they can more easily take advantage of whatever opportunities come their way.

Make sure you have a quality website with samples and professional business cards before doing contacting people from the directory. Either of them may be requested, depending on how technologically current your contact is. Our site is designed as a capabilities brochure, and we direct people there if they want to “look at something.” Do not rely on the site to actually bring you business. Encourage people to bookmark your site for future use, even if they have no current need. Also offer to send or drop off a business card. You can use the “what if you need someone quickly” approach.

Encourage them to consider you for a long term but intermittent relationship, perhaps 15 hours per month. It is not worth the time for a placement company to handle this kind of business so you do need not compete with them. It is also useful if your income is coming from multiple sources, especially in the current economic situation. Make a point of mentioning that your rates are the same as a placement firm would pay you, less their markup (use the word profit). Instead of emphasizing the cost of your services, hammer on the savings of using you directly instead of through a placement firm.

Think of this as long-term marketing. You will probably find that very few companies have a current need. Any contract situations that might come up will probably be in the future, perhaps three to twelve months out. It will be necessary to keep in touch with the decision-maker as time goes on or all of your effort will be wasted.

What type of companies should you contact for technical communication work? Manufacturing companies and software houses often need help. Anything high tech is probably good. Also be aware many Chambers have an employment page where members list current openings. Most people do not know about these listings, but they can be a good source of leads.

(c)2009 David Cherney
David Cherney is a General Partner in The Baird Group, which provides technical communications and custom training services. He is also the Employment Co-Chair of the Northeast Ohio chapter of STC. His company website is located at http://www.thebairdgrp.com.