Converting large complex unstructured set to structured.

Amy,

   I don't know what experience you have in working with XML, structured documents, EDDs, conversion tables, read/write rules, application definition files, and the other components of a FrameMaker structure application. You may not need them all. Especially if you are new to structure in general, I recommend that you don't try to learn everything at once. Start with something you do need--a structured template and an EDD and branch out to other components as you need them. It is always tempting to start by converting legacy documents. If your schedule permits, I recommend first setting up a structured template that you can use to experiment with structured documents. If you start with the conversion table, you may wind up with a structure that is optimized for adding structure to existing material rather than editing it once it's been structured.

   As far as the question of whether to define your own structure or use an existing one, I do not agree with the logic that using an existing model (such as DITA) gets you started earlier and saves you analysis time. Structure is all about organizing content, that is, organizing ideas and your project will provide the most benefit if you take time for planning at the beginning. That analysis might take the form of designing your own structure; it may take the form of figuring out how the elements and attributes defined in an existing model map into your own content. Remember that the industry-standard models are designed to apply to the documentation needs at many companies. They often make great examples for preliminary study, but they tend to be huge and much more complex than you may need. If you decide to go that route, strongly consider using a subset or specialization of the original model.

    Using a large tag set off the shelf is parallel to using a word processor without a style sheet. If the model was designed to let writers create almost anything, the model won't help writers create documents that conform to their own company's conventions. For example, one benefit of FrameMaker structured editing as compared to unstructured editing is that the context-sensitive available elements listed in the structured Element Catalog show only elements the writer is likely to need at the current point in the document. In contrast, the Paragraph and Character Catalogs show all defined catalog entries. Thus, if certain formats are only available within front matter or only for a title at the beginning of a larger unit, the format catalogs still show them everywhere. Suppose you start with a model that allows dozens of inline elements within a paragraph (emphasis, foreign phrase, part number, keyword, quotation, and so forth). If writers at your organization never use more than five of the inline elements, set up your application so that those five are the only ones listed.

   One of DITA's original design goals was to reduce the overhead that large companies like IBM required to publish documentation from new partners. The only way that goal could be achieved was with permissive rules for what's allowed where. Yes, DITA can be customized to support more stringent rules. Learning how to do so is part of the cost of using DITA. That expense may be worth it, but recognize it is there.

  The dividing line between a custom structure and a customization of one that is widely available may be blurry. My mother once had a cookbook with a recipe that concluded something like "bake for 20 minutes, or more, or less, it all depends." Designing a structured environment is similar. It all depends.

   --Lynne

Amy's original question was whether to use DITA or a custom structure. Scott responded by asking the preliminary question of whether to use structure. I hope my responses to both questions is still relevant. I'm going to split them into separate messages. I'll start with the value of structure first, here.

Reasons for using structure include:

• Promoting consistency of content organization and formatting within a single document and throughout a set of documents
• Enforcing many of an organization's content requirements
• Separating editing and formatting so that writers can concentrate on content rather than appearance
• Promoting reuse
• Creating documents that conform to the vendor-independent XML model so that they can be processed, if appropriate, by various XML tools
• Simplifying porting to non-FM editors, for example, to collaborate with an author who wants to use a different editor even as the original author works in FM
• Reducing the set of tags a writer must memorize (no need, for example, for different tags for the titles of chapters, appendices, and sections of various levels; they can all be formatted differently but still called the same thing)
• Using knowledge of the relationships among various elements to simplify several editing operations. It's a dozen years old now but http://txstruct.com/papers/FrameUsers02.productivity.pdf is still relevant. It's a summary of a presentation in which two users, one editing an unstructured FM document and the other editing a structured version of the same content, were asked to make the same changes. The user with the structured content finished much more rapidly in all tasks.

For many years, I would tell people that the most significant difference between structured and unstructured documents was the underlying model of a hierarchy of elements versus a sequence of paragraphs; they understood the concept if they understood the difference between a second-level heading, say, and a second-level section. I now consider that point to be the second most important. The most significant difference is that the writer of a structured document is creating data that must conform to programmatically-specified requirements. Whatever those requirements are (a custom model or DITA, DocBook, S1000D, or many other publicly-available models) allows processing such as the creation of various extracts or conversion to different forms based on those requirements.

--Lynne

Hi AMC...

The first question to answer is WHY are you converting to structure? And when you say "Structured Frame" are you assuming XML or are you just moving from unstructured FM to structured FM (binary files)? You should have a solid reason for doing this, and typically that reason will be based on the data model (DITA or other). Your question about which model to use leads me to think that you may not have done enough research to really justify the effort. Before you do anything, you should spend more time doing this research in order to determine the proper data model, and to justify the effort itself. This is not a simple task. Take the time up front to learn and understand what's involved and why it is (or is not) a good idea.

That said .. assuming moving to structure is a good idea for you, unless you have a really good reason to develop a custom model, I strongly recommend using one that already exists. The typical options are DITA (my preference), DocBook, and S1000D. Each model has it's pros and cons, and the appropriate choice is often determined by the industry.

The other issue of XML or structured FM is important to understand. In my opinion there is seldom a good reason to just move to structure without taking it all the way to using XML files as the source. Other people will likely disagree with me, but I feel like you often end up causing more problems and benefiting less by just using structured FM (binary) files. DITA won't work well as structured FM, and you won't benefit from the reuse possibilities as much. You also won't be able to take advantage of the wealth of tools available for working with DITA if you're not in XML.

If you do need to convert to DITA, you might want to take a look at a plugin that I offer called FM2DITA. Feel free to download the trial and use it to see what it can do. It also includes some documentation that may help you to learn more about the conversion process. Even if you don't buy the tool the sample field and information will help regardless of the data model you choose.

     http://leximation.com/tools/info/fm2dita.php

You may also want to watch this webinar that I did for Adobe ..

     http://leximation.com/downloads/adobe-fm2xml-2013/

Good luck!

…scott

Scott Prentice
Leximation, Inc.

www.leximation.com