FrameMaker or Word: Part 3

Featured

In 1998, I attended a conference held by the Society for Technical Communication in Anaheim, California. During that conference, I learned about single-source documentation. This term may seem a bit cryptic, but it means that you write a topic once, store it in a permanent location and link other documents to it when you need the information. The benefit of this approach is that you never have to write a topic more than once. If the topic requires an update, you can edit the source file and choose whether or not to update the linked content in your dependent files.

When I returned from the conference, I was no longer satisfied just to write documentation. Now I wanted to engineer it the way I had learned at the Anaheim conference. To that end, I began to experiment with mail merge in Microsoft® Word®. About a year later, I took a course on Adobe® FrameMaker® (FM) and easily mastered some of its most advance features for that revision. One of those features was conditional text. With mail merge in Word and conditional text in FM, I was able to use the same file to create single-source documentation for several vendors.

I was delighted that I could change entire documents from one vendor to another with the click of one button in Word and FM. That included all of the model names and several context-sensitive passages of content. If a vendor chose not to offer a product or function, each word processor automatically removed it from the content. Moreover, they’d also change content automatically between vendors. This capability not only saved time for my company but quickly delivered a significant return on investment. I had scored a major victory, but I soon realized that I had barely scratched the surface.

The next step was to make my single-source content accessible to paper-based, electronic and web documents. Furthermore, I needed to increase my knowledge and acquire better tools. FM supported structured writing with Extensible Markup Language (XML) and Standardized General Markup Language (SGML), but I seldom used it for my projects. Word saved to XML and Hypertext Markup Language (HTML), but the code it generated was not useful for most single-sourcing strategies. I’ve studied XML and HTML off and on for several years, but most of my projects required only one thing: content. Therefore, I focused on improving my communication skills.

Since then, the market has introduced several new word processors and single-source tools. As the list grows, we may find ourselves more confused than relieved. They all promise to make us more productive, but they miss some problems and introduce others. To overcome this problem, writers should be loosely tied to technology and tightly coupled with proven theory, sound practices and liberated imaginations. As the pace of change accelerates, staying current will challenge even the earliest technology adopters. Nevertheless, we can accomplish anything with Word, FM or any other tool if we use the best one we have: our minds.

Advertisements

FrameMaker or Word, Part 2

Featured

One of the most frequent complaints I hear when comparing Microsoft® Word® to Adobe® FrameMaker® (FM) is on the topic of autonumbering. Autonumbering in FM is stable and easy to maintain. In Word, autonumbering has caused nightmares, especially with long documents. On the other hand, I haven’t experienced problems with autonumbered captions such as figure numbers and table numbers for several years.

In the past, whether you wrote large or small documents in Word, you’d eventually run into the nagging issue of going back and correcting numbered lists. They’d restart when you wanted to continue from a previous list or continue from previous lists when you wanted to start a new list. After you thought you had corrected the problem, you’d notice something wrong, and realize that the autonumbering problem had reintroduced itself. It was a well-known and vexing issue to professional writers.

Over the years, I’ve experimented with better ways to create numbered lists in Microsoft Word. For a long time, I abandoned autonumbering for numbered lists and headings. I continued to define paragraph styles that would accommodate these design elements, but when it came to including a number, I typed it manually. That’s not a satisfactory answer when every second of productivity counts.

I also experimented with using captions as numbered headings. They were relatively stable. Why not? This approach appeared to work, but it had a terrible drawback: pagination does not recognize caption-numbered headings. For example, if you had a series of training modules, and you wanted to include the module number with your page numbers, it didn’t recognize the caption number in your first-level heading.

In Office 2007, however, Microsoft began to address the problems surrounding autonumbering. You can read an interesting entry about this issue on the Microsoft Word Blogs.[1] As of this writing, I use Microsoft Office 2010. In running several tests, I noticed that numbered lists appear to work better now than in previous revisions of Word. I still have to decide whether I want subsequent lists to continue autonumbering from previous lists or start all over again, but the autonumbering appears to be stable after I’ve made the initial selection.

Microsoft may have put this issue to rest. The question that remains is whether autonumbering works consistently with large documents. For that kind of project, I have the following suggestions:

  • Set a maximum page count for every file in your project
  • Maintain a unique file for every major division such as chapters and modules
  • Set a maximum number of heading levels (Four should be more than enough.)
  • Keep numbered lists short and free of multi-level complexity
  • Do not create a master document for a large project
  • Use Reference Document (RD) fields in a separate file for your Table of Contents

If you follow this advice, and create the appropriate paragraph styles in your templates, you should be able to avoid most autonumbering issues.


[1]Stuple, Stuart J. (November 6, 2011). Numbering is Not Possessed. Word Team. Retrieved on March 13, 2012 from http://blogs.office.com/b/microsoft-word/archive/2006/11/06/numbering-is-not-possessed.aspx.

FrameMaker or Word? Part 1

Featured

An image of a dollar sign taking off with booster rockets and flying into the sky

Boosting productivity (anibal: Fotolia)

I’ve created documents and templates in Microsoft® Word® (Word) and Adobe® FrameMaker® (FM). In one case, a supervisor asked me to build an FM template that matched the department’s Word templates in every detail. I completed that work in a few business hours. My next challenge was to support multiple versions of the same documents. I could easily handle that requirement with conditional text in FM, but what about Word?

I maintained five manuals ranging from 200 to 500 pages. I also created and maintained dozens of installation sheets. In addition to our own company, we had four original equipment manufacturers (OEMs) selling our product. The system I documented had over 50 different pieces of equipment associated with it, and each OEM wanted to rename them with their own model numbers.

Added to this complexity was the need to finish each version of each manual and take all of them through agency approval at the same time. Our approval process could easily last for years; therefore, it was essential to build the greatest amount of efficiency into the process as possible. It may seem unfortunate, but we could not use FM. We had to use Word. I knew FM well by this time, but I was the only one in my department with that knowledge and a license. My boss wanted to expand FM use, but he was turned down for additional funding.

Nevertheless, we still had to get the job done. Most technical communicators have watched this scenario unfold throughout their careers. It’s unpleasant, but it’s precisely at this point where our creativity has a chance to reveal itself.

I found one answer in mail merge with its conditional If-Then-Else fields. Mail merge enabled me to match the conditional text functionality in FM. I could drop large chunks of text for one OEM or add completely different language for another. By pressing one button I could automatically and reliably change passages of text and model names across an entire manual when the OEM changed.

I wanted to see if I could do the same thing with images. Eventually, I found several ways to change images by experimenting with the drawing tools in Word, using the IncludeText feature and the Building Blocks Organizer. I also discovered custom document properties, which enabled me to insert various passages of repeated text wherever I needed them.

Note: At first, I found that IncludeText was volatile, but I experimented and found a way to overcome that issue. I’ll discuss my solution in a separate entry.

Using Microsoft Word is not a limitation. The greatest leverage and value you can bring to any job is the flexibility to build a sound documentation practice on a strong theoretical foundation. Using the right tool for the right job is important enough, but it’s nowhere near as important as meeting client needs in a way that builds on previous investments and existing knowledge. Finally, the most powerful tool you can acquire is one you already possess: your imagination.