Structured vs Unstructured documents

Engaged ,
Apr 19, 2021 Apr 19, 2021

Copy link to clipboard

Copied

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.

Views

473

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines

correct answers 1 Correct answer

Advisor , Apr 20, 2021 Apr 20, 2021
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 ...

Likes

Translate

Translate
Adobe Community Professional ,
Apr 19, 2021 Apr 19, 2021

Copy link to clipboard

Copied

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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 19, 2021 Apr 19, 2021

Copy link to clipboard

Copied

@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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Apr 19, 2021 Apr 19, 2021

Copy link to clipboard

Copied

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

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 19, 2021 Apr 19, 2021

Copy link to clipboard

Copied

@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 :-).

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 20, 2021 Apr 20, 2021

Copy link to clipboard

Copied

@Barb Binder: Re publishing to HTML; I've not done that (yet). The formatting for our online content is slightly different from our PDF content. Any suggestions on how best to have a different formatting for HTML output in unstructured FrameMaker?

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Apr 20, 2021 Apr 20, 2021

Copy link to clipboard

Copied

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!

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 20, 2021 Apr 20, 2021

Copy link to clipboard

Copied

@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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Apr 20, 2021 Apr 20, 2021

Copy link to clipboard

Copied

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 

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Advisor ,
Apr 20, 2021 Apr 20, 2021

Copy link to clipboard

Copied

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

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 20, 2021 Apr 20, 2021

Copy link to clipboard

Copied

@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

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Mentor ,
Apr 21, 2021 Apr 21, 2021

Copy link to clipboard

Copied

One time I joked with Lynne that she probably does her grocery shopping list in structured FM. She clarified that it wasn't a joke. I wouldn't do it, but then again I don't make a list for groceries, because by now I know what I like so I get the same thing every time.

 

The short answer is that structured content provides overwhelming benefits, even if you don't care about fancy things like reuse. Just the automation of formatting alone is fully compelling. It just amazes me how many writers continue to occupy themselves with useless busywork, like having to think about starting a numbered list at 1. Humankind just managed to automate an aircraft flying in the martian atmosphere. If you have not yet automated a list starting at 1 every time, you should really think hard about your role in technology. 

 

Then, if you do want to take it to the next level with things like reuse, multi-channel publishing, etc. etc., you are ready. Structured content is the prerequisite for all these things. Nothing interesting happens any more without structured content that can be presented to automation processes like data.

 

It is a total myth that structured content only has value if you are a big company -or- you need heavy reuse -or- you have really long documents -or- you want to use a CMS -or- you want to streamline localization -or- you need to export XML -or- whatever. It has immediate value for the most basic of authoring workflows. And it is no harder than authoring unstructured content; in fact, I would submit that it is easier. If it is not, either 1) the template was poorly designed and/or 2) you might be in the wrong line of work.

 

Russ

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Advisor ,
Apr 21, 2021 Apr 21, 2021

Copy link to clipboard

Copied

One of the biggest advantages of structure is restricting writers to the organization's formats. You can give writers a well-designed unstructured template, but they can change paragraph and character formats or define their own at will. Structure ensures that all documents use the company's standareds.

 

Russ, you flatter me. I've never used structured FM for a grocery list. I do keep my Thanksgiving list in Excel. That way when I know how many guests are coming, I enter how many recipes of each dish I need, and get an update that includes the total amount of each ingredient I need that year. I have used structured FM to write email messages. I tend to rearrange what I'm writing as I edit, and structure makes doing so very easy.

 

 

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 21, 2021 Apr 21, 2021

Copy link to clipboard

Copied

@Russ WardYou make a compelling argument.

@Lynne A. PriceYou have a valid point about authors changing paragraph formats.

 

Question to you both: With structured documents, wouldn't writers still need to select the correct elements just like they have to select the correct paragraph style in unstructured documents?

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Mentor ,
Apr 22, 2021 Apr 22, 2021

Copy link to clipboard

Copied

Answering this question, "With structured documents, wouldn't writers still need to select the correct elements just like they have to select the correct paragraph style in unstructured documents?"... yes. Writers still need to be writers. But the structure rules can take care of so much that is normally a manual hassle. Going back to the numbered list example. The author has to decide that they want a numbered list and select the correct element to start it. Once the element is selected, formatting rules automate the rest. The author just writes the list and doesn't worry about formats. The rules make the first item #1 automatically, and the author can rearrange, add, and delete items and the numbering adjusts automatically. And as was mentioned earlier, a typical ruleset uses an identical structure for numbered and bullet lists, except for the top level element. So the author can convert between the two with a few clicks.

 

There is musch much more. Maybe I want to have sublists (common). Or maybe my lists look different in different places, like maybe they have a different font size in tables. I never have to think about any of that. Any time I want a list, I just pick "list" and the rules format it correctly for the current context. If I move the list anywhere, (copy/paste/drag/etc) it automatically reformats according to where I put it.

 

This is a small example and alone may not merit some big migration. The point is that authors do these little things all the time. For me the collective benefit of all these little things over the years is enormous. It would be impossible to quantify the time savings, but I'm sure that it is remarkable. All the time I am drafting, moving things around, etc. etc. At any given time, I have 10 or less elements to pick from, even though there are over 200 paragraph formats in the underlying template. The structure rules are making all the contextual decisions for me. I spend time writing, not fussing with formats.

 

And that is just the beginning. You should see the fun stuff I'm doing with conditional content and information reuse, all driven by automation that is made possible by the structure markup 🙂

 

Russ

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Mentor ,
Apr 22, 2021 Apr 22, 2021

Copy link to clipboard

Copied

Sure wish the "edit" function worked so I could fix "musch".

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Apr 22, 2021 Apr 22, 2021

Copy link to clipboard

Copied

Russ Ward: Sure wish the "edit" function worked so I could…

Get yourself promoted to ACP (or whatever it's to be next called), and you [re]gain Edit (which all users used to have, and even ACPs lost for a while). Adobe is apparently still trying to figure out how to prevent abuse of the feature.

re: If you have not yet automated a list starting at 1 every time, you should really think hard about your role in technology.

For my recent project, I actually needed to be able to start a list at 0, 1 or a.

But to be sure, FM is a tool only suited for use where there is a document architect:

  • Unstructured, with robust templates and an enterprise style guide explaining their use.
  • Structured.
  • Automated, where the content authors essentially fill out forms, which are then rendered by FM Publishing Server.

If my recent project needs translation, I may well recast it as structured.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Advisor ,
Apr 23, 2021 Apr 23, 2021

Copy link to clipboard

Copied

Bob,

   Allow me to disagree with a couple of your claims.

   There are a huge number of structured documents that are not rendered by Publishing Server. 

   And structured authoring is no more comparable to filling out forms than unstructured authoring in an organization that has a detailed style guide that specifies required content and its order. Furthermore, a structured template can be very general, simply defining a few basic elements such as Document, Title, Paragraph, List, Item.

    --Lynne

 

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Apr 23, 2021 Apr 23, 2021

Copy link to clipboard

Copied

I fear I didn't make myself clear, but I don't disagree with Lynne.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Apr 21, 2021 Apr 21, 2021

Copy link to clipboard

Copied

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 

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 21, 2021 Apr 21, 2021

Copy link to clipboard

Copied

@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 :-).

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Adobe Community Professional ,
Apr 21, 2021 Apr 21, 2021

Copy link to clipboard

Copied

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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 21, 2021 Apr 21, 2021

Copy link to clipboard

Copied

@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.

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Advisor ,
Apr 24, 2021 Apr 24, 2021

Copy link to clipboard

Copied

Good points, Rick. To add to each of them:

 

1. The Element Catalog is only part of guided editing. The other is the Structure View, an optional window that shows a document's element hierarchy in an outline-like indented arrangement that makes it clear where elements are missing or occur where not allowed. The Structure View is instantly updated as the user makes changes. This approach allows a document to go through invalid states. For example, a writer might compose the content of a section first and then go back and add its title.

 

2. Other advantages of XML include allowing contributors from different organizations using different tools to collaborate on a document. It also allows a component manufactuer to supply documentation in a vendor-neutral form that its customers can than incorporate into its own documentation for completed products. FrameMaker provides these and other XML advantages will allowing authors to edit in a WYSIWYG environment.

 

3. Validation certainly makes any downstream processing easier to implement. It is also a way of enforcing an organization's style guide during editing. For example, if editorial conventions require, a structured environment can prohibit "lists" containing only one item, a section containing a single subsection, or a list that does not have an introductory paragraph. If every user manual must have certain sections in a required order  (safety information, installation, use, maintenance, warranty, error messages), validation shows the writer when sections are out of order or missing.

 

   --Lynne

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines
Engaged ,
Apr 28, 2021 Apr 28, 2021

Copy link to clipboard

Copied

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 :-).

Likes

Translate

Translate

Report

Report
Community guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
community guidelines