Click to print this articleFrameMaker Chautauqua 2006

by Fei Min Lorente, Volunteer Co-ordinator

A chautauqua is a travelling meeting for the purpose of education. That's the name of the annual FrameMaker Conference, which was held this year in Austin, Texas, November 8 to 10. Bright Path Solutions organizes it, and it's full of FrameMaker users and vendors. Feel the love!

As a FrameMaker supporter myself, I felt quite at home with the other enthusiasts. However, emotional divisions appeared when we discussed unstructured FrameMaker, structured FrameMaker, and DITA. For the uninitiated:

unstructured FrameMaker
Using FrameMaker to apply formatting to your document.
structured FrameMaker
Using FrameMaker to tag "things" in your document. The tags are called elements, and they can be named to reflect what something is instead of how it looks. Every element can have attributes (or information about the element, called metadata). Structured FrameMaker can involve XML if you choose.
Darwin Information Typing Architecture (DITA)
A standardized XML architecture that includes a standardized way to extend the structure to meet your particular needs. It's a cool idea that is explained well in Introduction to the Darwin Information Typing Architecture.

The following article explains my views on the advantages and disadvantages of each of the three ways of using FrameMaker, drawn from the various presentations at the conference, and by talking to other attendees. I have attempted to be objective about this, but apparently no one can be completely objective.

Unstructured FrameMaker

Most FrameMaker users use unstructured FrameMaker. FrameMaker was unstructured from the beginning, and it does an excellent job of producing documentation. It even enables you to produce different flavours of documentation from a single source if you use text insets and conditional text. Since it isn't broken, why change it?

Unstructured FrameMaker is the easiest to understand—we're all familiar with formatting. Simply choose the font, the size, the space above and below, any autonumbering, and you're done. Also, you can write in a natural narrative style and do not have to think about the elements of structured writing.

FrameMaker began as a desktop publisher, so all of its features work in that environment. When structured FrameMaker was developed so that documents could be structured world be compatible with XML, a few things did not translate well, like text insets, conditional text, and custom table formatting. You can still use these features in structured FrameMaker, but if you're importing from or exporting to XML, you'll need some help with these ones—more on this shortly.

I can certainly understand why a lot of people cannot find time to investigate and use structured FrameMaker, but ever since the SGML version 6.0, they are missing out on the inherent features of structure. As of version 7.0, everyone gets structure capability with the regular FrameMaker, and it's just sitting there quietly, waiting for them to notice it. I think the problem is that they don't know what they're missing.

Structured FrameMaker

Structured FrameMaker allows you to give more information to FrameMaker so it does more work for you. A concrete example is that FrameMaker can format things based on their context. If you define an element called Title, and set up structured FrameMaker to use particular formats depending on where that Title appears, you will never again have to tag each title Heading1, Heading2, Heading3, or anything else.

In general, structured FrameMaker reduces your formatting time. As you drag and drop units of information (elements), they automatically look different. You don't even have to think about it. Just imagine, no more FirstNumberedItem, NumberedItem, LastNumberedItem! No more applying paragraph tags when you change the order of items in your list!

To help you work with structure, which is hierarchical, FrameMaker provides a Structure View. This window has the added benefit of allowing you to drag and drop chunks of text (anything enclosed in an element). You can also collapse the elements so that you're only seeing the highest-level ones and immediately choose the section you want with a minimum of scrolling.

Example of a Structure View

Example of a Structure View

Furthermore, if you have a group of writers, structure helps to keep everyone consistent because you've reduced the number of formatting choices they can make. Any deviation from the architecture shows up in red in the structure view. Any customizations are easily wiped out by importing the structure again.

If you choose to venture into the world of XML, you have the opportunity to automate more of the documentation process. For example, XML is ideal for publishing information from databases or source code. If you have consistently formatted data to work with, a programmer (or you) can write some sort of script, and you can turn that information into an XML document that complies with the structure you've defined in FrameMaker, import the XML and instantly have a formatted document.

With structured FrameMaker, you can even attain the dream of collecting information from Subject Matter Experts (SMEs) without having to reformat their writing. If SMEs choose to work in FrameMaker, the structure helps to guide them through the writing process. It certainly reduces their interest in features like the paragraph and character designers. If SMEs choose to work in their favourite editor, they can give you XML that automatically formats when you open it in FrameMaker.

If you have FrameMaker 7.0 or later, and you want to know more about XML, structured FrameMaker provides a gentle introduction to XML principles and it's free! Compared to the heavy-duty XML tools, FrameMaker is easy learn when you want to define a customized structure. Most significantly, it's easy to relate that structure to a format! Creating names for elements and setting them up in a hierarchy is the easy part; telling your tools what you want each element to look like (on your screen and in the final output) is hard to do without learning XSL or XSL-FO. FrameMaker simplifies the process by associating the elements with FrameMaker formatting, and then you can use your usual tools to produce HTML and PDF files.

Since both structured and unstructured documents are all FrameMaker documents, you don't have to convert all your documents simultaneously. If you have older documents that are not being revised much, you don't have to convert them at all. The deliverables will look the same, regardless of whether they are structured (or not) in the FrameMaker files. You can make the transition to structured while continuing to publish documentation.

Finally, structure encourages consistency and modular writing which are bound to be helpful sooner or later. At some point in the evolution of your documentation set, you are going to want to make sweeping changes, whether it's for translation or because you're changing to a new editing tool, or you have to provide a new deliverable format. Structure will make that sweeping change much less painful, and may even be the factor that makes it possible. Furthermore, if you can convert to XML, then you have the chance to automate those sweeping changes with a script.

There are some drawbacks to structured FrameMaker. If you use XML, not all FrameMaker features are supported. That is, you can use them in FrameMaker, but they won't be preserved if you export them to XML and import them again (round-trip). On the bright side, many people have developed plug-ins to take care of the more critical features, like conditional text and text insets. If it's important to you, chances are it's important to someone else, and that someone may have found a solution that they're willing to share.

The unavoidable drawback is that it takes time to learn structured FrameMaker and set up the supporting files. When you're busy writing to a deadline, you won't have time to think about this, much less do it. However, if you can squeeze it into your busy schedule, or if there's a lull between releases, it's worth the investment in time. To give you an idea, I took about 120 hours to learn and set up the first working structure for a complete manual, having no previous knowledge of XML or structured FrameMaker. This did not include converting any legacy documents, and more time was spent over the next couple of years refining and tweaking the structure as things came up.

You could take less time because Adobe provides better resources now to get you started. You could also reduce the learning and set-up time if you went on a course, or hired a consultant. You could take more time if you have more documents than I do, or if they use more FrameMaker features, or if you have to work with a committee. ;-)

DITA

DITA is standardized XML, and it's the latest buzzword. Many of the tool vendors are providing support for DITA, which means they should already know how to display this structure, and you won't have to explain it to the tool. Standardization has a lot of advantages (and some disadvantages).

The difference between DITA and using any old form of XML is that it makes the interchange of documentation with other companies easier. Although XML is theoretically transferable as long as you provide its DTD or schema, in practice, both companies have to have the same tools because the interpretation of the structure to format is tool-dependent. With DITA, you don't have to have the same tools. This is especially handy if you have to deal with translation companies or Original Equipment Manufacturers (OEMs), who provide their documentation to you so you can then incorporate it in your documents.

Using DITA means that you don't have to figure out a sensible structure for yourself and learn from your mistakes. Many people at IBM with lots of experience with documentation have worked on DITA, and they've made and fixed the mistakes for you. Now that it's in the hands of the OASIS standards organization, even more people are involved to ensure the highest quality.

If you've heard of DocBook, you might be wondering why we need another standard, but DocBook was modeled on a printed book structure, and it tried to be everything to everyone, and ended up being too cumbersome to use. At the other extreme, people would trim DocBook to suit their own purposes, and then it wasn't a standard anymore. DITA solves that problem by starting with three basic types (concept, task and reference), and allowing extensions and specialization, all within the standard.

Writing to the DITA standard is ideal for re-use. Since you have to put your information in discrete chunks that are tagged semantically (according to what they mean, not how they look), you have a much better chance of getting a piece of information that can be used in more than one place and in more than one context. This sort of organization seems to beg for a Content Management System (CMS), but before you start protesting that you could never afford one, consider how much you can accomplish with a file structure, well-planned file naming conventions, and a file versioning system.

From what I heard at the conference, one of the hardest parts of making the transition to DITA is writing for a topic-oriented structure. Perhaps if you are accustomed to writing for online help, it would be similar, but if you really had to write each chunk as if it could be re-used anywhere, I think that would be a challenge.

Someone asked one of the DITA presenters if there were situations where he would not recommend using DITA, and one of the cases he mentioned is a lone writer situation. DITA involves more overhead than is necessary for a small documentation set.

I also got the feeling that many people found the concept of DITA overwhelming. The experts also added that they don't recommend making a leap from unstructured FrameMaker straight to DITA.

In Summary

You might have noticed from the relative length of each section that structured FrameMaker is my favourite. There are many benefits that unstructured FrameMaker users could derive from changing to structured, if only they had the time to learn it and implement it. Legacy documentation can even be left in unstructured FrameMaker, so there needn't be a large conversion cost.

My current situation as a lone writer does not warrant the adoption of DITA. We do not translate our documents, nor exchange them with an OEM. We rarely re-use information in discrete chunks, and what we do re-use can be handled with conditional text, text insets, and cross-references. Most of all, my information is written by the SMEs, and I can't imagine training them to think and write in re-usable topics. However, as tool support grows for DITA, and because we use Eclipse which is also an IBM creation, I might have to adopt DITA in the future. If I do, converting documentation from XML will be easier than converting unstructured documentation.

More Information

There's always more information about these hot topics:

The Challenge

As I said at the beginning, these are emotional topics. People were passionate about promoting whichever mode of FrameMaker that they used. What I have presented are simply my opinions from attending the FrameMaker Chautauqua and other presentations. While I have experience with unstructured and structured FrameMaker, I haven't actually tried to use DITA in FrameMaker or elsewhere. If you would like to express a different opinion, or correct my view of the "facts", then quill@stc-soc.org of The Quill. She'd love to hear from you, and so would I.

Fei Min Lorente

About Fei Min Lorente

Fei Min is working at AMI Semiconductor Canada Company, running her own business called Articulated Concepts on the side, and is the current Volunteer Coordinator. She has held other council positions in the Alberta Chapter, including secretary and vice-president. When she's not doing technical writing or family stuff, Fei Min fills in the spare minutes with scrapbooking. When she needs stress relief, she bakes.

 

In this issue:

Contents | President's Message | Customers | Director | FrameMaker | Learning | Membership Value | Profile | Student Awards | Minutes