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.