Legend

Answered

Structured vs Unstructured documents

Forum|Forum|4 years ago
April 19, 2021
9 replies
4467 views

This poor horse is most likely beyond rescue from all the flogging, but I'd like to resuscitate the poor creature.

I've been using Framemaker (Unustructured) for the past 15 years, starting on FM 7. I've always had to work with styles and tables defined by others. A few years ago I was in the position to redesign the styles (paragraph and character) and tables for our training manuals (book) to bring them into line with our corporate style guidelines. This resulted in 3 primary documents:

Template_Master.fm: This is the master template all documents is created from.
Variables.fm: This documents contains the standard variables used across all manuals. A copy of this file is created for each manual (book) with the variables updated accordingly.
ConditionalText.fm. This document contains all the standard conditions used across all manuals. A copy of this file is created for each manual (book) with the relevant conditions applied.

When a manual (book) is updated and prepared for publication, File > Import >Formats is used to update all formats, definitions and styles from the Template_Master, then the Variable Definitions are updated from the Variables document and lastly, the Conditional Text Settings from the ConditionalText document.

This process has served us well for the last few years, except when a new Variable or Conditional Text Setting needs to be added. However, as the Keeper for our training collateral, I'm starting to wonder if switching to Structured documents is the way forward. I've seen many forum posts and have found many documents/youtube videos on creating and using structured documents in FrameMaker. I'm concerned that the interface for Structured Framemaker would be too overwhelming for our writers/editors. Most of our writers/editors' skills are limited to using MS Word (personally, I think writing any kind of manual in Word is like cutting a diamond with a sledge hammer - it'll do the job but it ain't going to be pretty!). They're used to applying Styles to text (a la Word), so the concepts of Elements would be too foreign for them.

I'd appreciate feedback from the community on whether there would be any benefit/advantage to us switching to Structured FrameMaker, or whether we're best to continuing with our exsiting process.

This topic has been closed for replies.

Correct answer Lynne A. Price

Decades ago, I lost count of the number of times I heard a comment to the effect that "you wouldnt use structure to write a letter to your mother." Well, if my mother were still around, I certainly would.

Of course there is a lot of dependency on the nature of the content being edited, but a well-designed structure let's the writer concentrate on the logic of the material rather than how it looks. Formatting is a side effect. Let me give you a few examples:

1. Suppose your document contains numbered lists, with the first item resetting the counter to 1 and other items incrementing the counter. In an unstructured document, you'd typically have two paragraph formats, one to initialize the counter and one to increment. To reverse the order of the first two items, a writer must move one or the other and retag them both. In a structured document, the writer simply drags one to the new location and their autonumbers are both automatically changed. The automation is possible because the objects the writer uses include the entire list as well as its items. The rules that control the formatting can specify something that happens for the first (or last) item in a list as well as to all items.

2. Suppose you use italics for foreign phrases and bold for emphasis. In an unstrutured document, you might have a character format called Foreign and another called Emphasis. If you apply both character formats and the properties defined for each are applied, but the character text is that of the last applied. If you decide to switch from bold to red, you might have to search for bold text rather than a character tag. Of course, the task is more time consuming if you also use bold for part numbers and product names. In a structured document, you can have a Foreign element inside an Emphasis element or the other way around. The rules for formatting either or both can be changed as the organization's style sheet evolves. It's even possible for different formatting properties to be set in different contexts (within a title, say, or a table cell).

3. Suppose you have a document with a bulleted list that is 20 or 30 pages long. You want to change it from a bulleted list to a numbered list. If the document is instructured, you have to find the first item (or the last item) and either drag to the other end, or shift-click on the item at that end. Once you have the entire list selected, you can apply the paragraph format for numbered items, remembering to use that specical format for the first one. And if many of the items have sublists, you'll either have to go item by item instead, or retag the items in every sublist as well. In a structured document, you don't have to see both ends. In fact you don't have to see either end. Simply click in one item and then extend the selection to the element containing the current element, that is, extend the selection from the item to the list.And then change the type of list. All items are changed; sublists are preserved.

4. Suppose you are writing user manuals for household appliances. Every manual has the same sections in a required order: Safety Information, Installation, Use, Care, Troubleshooting. That order can be build into the structure rules. A new writer doesn't have to memorize it. And because the headings are fixed, their text can be automatically generated with no risk of typos.

I once heard a presentation in which the speaker explained that when his son was in 2nd grade, he talked about his homework in terms of chapters and sections. By the time he was in 5th grade he explained that his assignment was to start reading from the 2nd level heading on page 82. We do two things with written material; format it and work with the information it contains. Structured documents let you create nested logical chunks and the formatting is automatic based on the contexts in which those chunks (called elements) occur.

--Lynne

QuintinSeegersAuthor

Legend

Not to resurrect an old post, I thought I'd share a funny little story about how this project is going.

As you all would have noticed, I been inundating the forums with my questions about EDD's, conversion tables, etc. (Apologies after the fact!).

Today I had to put together a new document within a few hours (don't you just love those projects with deadlines within a few hours!). As our conversion to Structured Framemaker is still a way off, I had to create the document in Unstructured Framemaker. Ugh! The constant battle of 'which paragraph style should I use here again?', 'If I did this as a structured document, I didn't have to think about which bullet/heading style to use here' and 'In a structured document, all these extra bits would be created automatically.'

So, it's official. I've been converted to a Structured FrameMaker supporter! (Disclaimer - I will be posting more questions!)

S

Stefan Gentz

Community Manager

Love that! It's something I hear often: At the beginning, it's a little bit painful, but once you're there, you never want to go back.

QuintinSeegersAuthor

Legend

Thank you for everyone's input on the subject. A special mention for @Lynne A. Price who spent an hour with me today to give me an overview of Structured Framemaker.

We'll be taking the plundge and covert to Structured Framemaker.

Now the fun of designing our EDD begins, so you may see me asking some (silly) questions :-).

frameexpert

Community Expert

I am going to weigh in here with a few things that may not have been mentioned.

1) Guided authoring. The user's Element Catalog can be set to only show valid elements for the current cursor location in the document or Structure View. This means that new authors can be "guided" through the creation of a document even if they are not familiar with its style guide, etc. For example, a section element may require a child "title" element so title will be the only choice in the Element Catalog when the cursor is at the top of the section element. This is a great shortcut for training new writers on manuals that they may not be familiar with.

2) Vendor-neutral document format. While you can save structured FrameMaker documents as binary .fm files, you can also save them as .xml files, which gives you a vendor-neutral format for your content. This is valuable if you decide to move away from FrameMaker in the future.

3) Validation for predicable down-stream processing. Structured FrameMaker documents can be validated to insure that their content is structured correctly, based on the EDD rules. The advantage here is consistency and the fact that valid documents can be post-processed predictably and reliably. For example, when converting to HTML from structured FrameMaker, you can have conversion rules that will work because the structure of the FrameMaker is known as long as it is valid. This prevents author "freestyling" that often breaks down-stream processes.

QuintinSeegersAuthor

Legend

@frameexpertThanks for that. Your 1st point is one of the 'complaints' I always get when teaching new writers: "FrameMaker has a steep learning curve. Word is so much easier to use." The last statement usually elicits my response about cutting a diamond with a sledge hammer! I can definitely see the advantage of this 'guided' approach.

Barb Binder

Community Expert

Glad to see the structured users weighing in. 😊

I will note that unstructured FrameMaker can restart lists automatically. You don't need to remember to do it—you just need to add the instruction to your unstructured template. 😉

~Barb

~Barb at Rocky Mountain Training

QuintinSeegersAuthor

Legend

@Barb BinderYes it is. And their import is appreciated and definitely food for thought.

I did a quick count and we currently use 67 paragraph styles, 7 characters styles and 7 table styles. So maybe there is benefit to our writers not having to know when to use each of those paragraph styles :-).

L

Lynne A. PriceCorrect answer

Inspiring

Decades ago, I lost count of the number of times I heard a comment to the effect that "you wouldnt use structure to write a letter to your mother." Well, if my mother were still around, I certainly would.

Of course there is a lot of dependency on the nature of the content being edited, but a well-designed structure let's the writer concentrate on the logic of the material rather than how it looks. Formatting is a side effect. Let me give you a few examples:

1. Suppose your document contains numbered lists, with the first item resetting the counter to 1 and other items incrementing the counter. In an unstructured document, you'd typically have two paragraph formats, one to initialize the counter and one to increment. To reverse the order of the first two items, a writer must move one or the other and retag them both. In a structured document, the writer simply drags one to the new location and their autonumbers are both automatically changed. The automation is possible because the objects the writer uses include the entire list as well as its items. The rules that control the formatting can specify something that happens for the first (or last) item in a list as well as to all items.

2. Suppose you use italics for foreign phrases and bold for emphasis. In an unstrutured document, you might have a character format called Foreign and another called Emphasis. If you apply both character formats and the properties defined for each are applied, but the character text is that of the last applied. If you decide to switch from bold to red, you might have to search for bold text rather than a character tag. Of course, the task is more time consuming if you also use bold for part numbers and product names. In a structured document, you can have a Foreign element inside an Emphasis element or the other way around. The rules for formatting either or both can be changed as the organization's style sheet evolves. It's even possible for different formatting properties to be set in different contexts (within a title, say, or a table cell).

3. Suppose you have a document with a bulleted list that is 20 or 30 pages long. You want to change it from a bulleted list to a numbered list. If the document is instructured, you have to find the first item (or the last item) and either drag to the other end, or shift-click on the item at that end. Once you have the entire list selected, you can apply the paragraph format for numbered items, remembering to use that specical format for the first one. And if many of the items have sublists, you'll either have to go item by item instead, or retag the items in every sublist as well. In a structured document, you don't have to see both ends. In fact you don't have to see either end. Simply click in one item and then extend the selection to the element containing the current element, that is, extend the selection from the item to the list.And then change the type of list. All items are changed; sublists are preserved.

4. Suppose you are writing user manuals for household appliances. Every manual has the same sections in a required order: Safety Information, Installation, Use, Care, Troubleshooting. That order can be build into the structure rules. A new writer doesn't have to memorize it. And because the headings are fixed, their text can be automatically generated with no risk of typos.

I once heard a presentation in which the speaker explained that when his son was in 2nd grade, he talked about his homework in terms of chapters and sections. By the time he was in 5th grade he explained that his assignment was to start reading from the 2nd level heading on page 82. We do two things with written material; format it and work with the information it contains. Structured documents let you create nested logical chunks and the formatting is automatic based on the contexts in which those chunks (called elements) occur.

--Lynne

QuintinSeegersAuthor

Legend

@Lynne A. PriceThanks for that detailed reply :-).

Point 1 is very valid in our case in that we have a paragraph style for the first item in a numbered list and another style for the subsequent numbers. However, it would never happend that the order of the first and second item would need to swap - rather a change in order of the subsequent numbered items.

Point 2: We have very strict style guidelines on the use of bold/italic/colour and there are only two character styles writers can use - one of emphasis and another for hyperlinks. If there was a change in how these are formatted, the character style would be updated by myself only. There are also stict guidelines on when these character styles may be used.

Point 3: I can see the advantage there for late lists, though we typically only used numbered lists for process steps and bullet list for other lists.

Point 4: This would be an advantage as all our manuals do have a set layout, i.e. cover page, legal disclaimers, a few other standard documents depending on the product and a back page. Though, these are standard documents that are simply added to the book and does not require the writer to add/modify the content for those documents.

I suppose it comes down to two questions: Do the benefits gained warrant the time and cost to convery to structured documents, including retraining writers/editors? Are the benefits gained from structured documents actual benefits or just 'perceived' benefits?

At this stage, in our circumstanced, I'd have to answer No to both questions

Barb Binder

Community Expert

You can use condition tags to hide/show content for the print and HTML versions, if it differs. And you can control the HTML structure/formatting in the Publish pod. No structured users have weighed in, yet, but so far it sounds like there is no need to complicate your workflow by making the switch.

~Barb

~Barb at Rocky Mountain Training

Jeff_Coatsworth

Community Expert

From my limited understanding of structured authoring, the benefits of going that way kick in when you have a lot of content reuse, a need for localization (translation), or require integration to some external content server that's looking for XML content "chunks". For multiple authors, a good Content Management System (CMS) is a must. YMMV!

QuintinSeegersAuthor

Legend

@Jeff_Coatsworth: We have some content reuse (perhaps 15%). As our training covers Australia and New Zealand, there is some localisation (about 25%). We don't have multiple authors on the same manual - a manual is only worked one by one writer/editor at a time, so no real nead for a CMS.

Barb Binder

Community Expert

Hi @QuintinSeegers:

I'm another unstructured FrameMaker user and also design templates. I agree with Bob, and recommend adding any new content (i.e., new Variable definition or Condition Tab) to the template, and then import the content to all of the chapters via the Book windows File > Import > Formats. Just be sure to avoid overrides in the documents.

And you can certainly use the Publish pod to export content to HTML from unstructured FrameMaker.

~Barb

~Barb at Rocky Mountain Training

QuintinSeegersAuthor

Legend

@Barb Binder: That's our process too. Whenever a new Variable/Condition is needed, it is added to the Variables/ContitionalText templates and then gets applied to all the documents in the book. As the Keeper, I'm very strict about overrides - they will get overwritten when templates are applied, so using them is a waste :-).

Bob_Niland

Community Expert

re: Template.fm

I ended up doing exactly that for a recent unstructured project. The template itself ended up being 142 pages, 67% of the page count of the work it supported, with no regrets.

In addition to being the repository of all the formats & definitions, the template included supporting narrative on each choice, and sections on step-by-step workflow. I often had the latest Template.pdf open while editing the main work.

Doing it this way trivially supported some otherwise painful processes, including migrating the project from FM7 to FM15, and completely changing the font families.

A separate subordinate Template_print.fm was also created to deal with the issue of print pages needing a wider gutter than convenience PDFs. If I get to eBook or HTML output, similar subordinates are expected. Import, AMP, update, render, done.

The timeline didn't provide the luxury of learning structured FM and architecting for it. About the only thing structured might have provided is a more elegant way to implement the zillions of spot cross-references required, which I ended up doing as a margin-anchored-frame hacks in Color Views.

QuintinSeegersAuthor

Legend

@Bob_Niland: Our Template_Master.fm also character stules for cross-references as well as formats for cross-references, so our writers/editors have only 2 formats to choose from - one for the text only, another with the text and page number.

Some of our training courses are converted to online courses, so having the content output in HTML might make it easier to display the information online. So far, this the the only benefit I can see for us to move to Structured.

Sign up

To post, reply, or follow discussions, please sign in with your Adobe ID.

Sign in to Adobe Community

To post, reply, or follow discussions, please sign in with your Adobe ID.

Scanning file for viruses.

This file cannot be downloaded