Is Structured FM12 the right solution for this problem?

[Guest]

I've been tasked with solving a tricky problem at my office. Briefly: We've got a technical manual that needs to be printed each time we sell a piece of equipment. Currently, the manual is produced using a combination of MS Access DB and a convoluted Word doc that uses Mail Merge to pull data from the Access DB into the appropriate fields. The DB has a hundred tables or so, and some of the tables are "calculated" values - i.e. the value in the fields is calculated based on values entered in other tables within the DB. The Word doc uses some kind of "if-then-else" logic to determine which tables to use for which fields when building the doc. This whole setup is currently maintained by the engineering, sales, and marketing departments.

We currently use FM11 (unstructured) in the Technical Writing department, and my boss is asking me to figure out a way to migrate the Access/Word doc described above to a format we can use so we can take ownership of the documentation process for this particular line of equipment. I suspect the variables involved here go way beyond what we can do with conditional text and variables within FM, but I'm wondering if Structured FM (either 11 or 12) is more suited to this project, either by using some sort of conduit between FM and an SQL DB, or directly within FM using conditinal text, variables, or some other organizational function present in either FM11 or FM12.

Any guidance here would be appreciated. I'm not even sure what questions to ask at this point to get a proper shove in the right direction.

[Lynne A. Price]

TW,

  Without knowing the details, I can't say with absolute certainty that structured FM (11 or 12) would be a good solution. From what you've said, though, it seems likely.

  Is Technical Writing going to be taking over maintenance of all the information, or are the other departments still going to be contributing? Will a database still be used?

  I don't know how familiar you are with structure, XML, or XSLT, but two techniques available in structured FM come to mind. One is "filter by attribute" which, like conditional text, allows you to show or hide parts of a document, but is based on attributes of the elements in a structured document. The other is XSLT. As you probably already know, XML is a vendor-independent text-based representation of an element hierarchy. Structured FM was designed to use the same model and with some forethought it is straightforward to move XML material into structured FM. XSLT is a programming language for transforming an XML document into another XML document or other text-based format. XSLT can duplicate the if-then logic of your current Word document. Furthermore, most databases allow you to save search results as XML. Thus, a practical solution, may well involve using XML, possibly manipulated with XSLT, to incorporate information from a database.

  Feel free to contact me off-list (lprice at txstruct.com) if you'd like to discuss in more depth.

      --Lynne

[Gorly]

Hi,

I'd support what Lynne already mentioned. Get that SQL queries into XML directly or into CSV and transform the CSV into XML via XSLT. Then get the stuff into structured FM with an appropriate template.

There is really no excuse to do that with word

What keeps me wondering is, why your process uses if/then/else logic within word. When you pull stuff from a SQL database usually the SQL query already inherits the logic for the output.

Sure you can postprocess the stuff with VBscript, XSLT or any other scripting/programming language, it just doesn't make much sense

But if you can generate XML, have already FM 11 at hand and need printed output, it is just a matter of some small effort to get some pdf/printed output from that constellation.

-Alex

[Russ Ward]

Hi,

My take is that you are looking at a convoluted process no matter what. But in saying that, I don't think it's necessarily a bad thing. It sounds like innovation to me.

When it comes to the automation of building documents, FrameMaker is a real powerhouse in the field. You have an enormous variety of options, especially if you choose the structured file route. Like Lynne implies, it is not really possible to say with certainty whether FrameMaker is the right tool without some in-depth analysis, but I think it likely that it can do the job. Lots of things to consider though, such as your publishing requirements, tool familiarity, budget, etc. etc.

I would naturally gravitate towards FM, but my attitude is skewed by the fact that I am experienced with scripting and structured content within FM. I know that with the right skills, you can make it stand up and dance. But that might not be the skill set you have, you want to have, or you want to pay for.

Just some thoughts.

Russ

[Guest]

I love this line: Get that SQL queries into XML directly or into CSV and transform the CSV into XML via XSLT. Reminds me of that bit in "Good Morning, Vietnam" where Robin Williams goes through the routine about the Vice President: "Well, sir, since the VP is such a VIP, shouldn't we keep his ETA on the QT? Otherwise, he might get KIA and then we'd all be on KP." And now, back to work...

I'm going to try to answer all of the questions above, in order, and add a little info where appropriate.

• TW dept may or may not take over all maintenance of the doc. That's one of the recommendations I'm tasked with providing. My current thinking is, engineering should remain in charge of entering relevant tool data to the data repository, sales should provide TW with a "spec sheet" of what was sold, and TW should then use the specs to "build" the document for customer release.
• Will a DB still be used? Unknown. That seems the best way to catalog and access the data, but I'm open to alternatives if there are any that make sense.
• I am totally unfamiliar with structure, XML, DITA, HTML, etc. Literally 100% of my experience with FM has been in the unstructured workspace. This whole structured FM inquiry was inspired by a blurb in my "Unstructured FrameMaker 11" book (from p474: "If you need to use complex combinations of condition tags, consider setting up a workflow in the structured interface of FrameMaker. Structured documents allow you to create versions based on attributes, which are easier to use and more powerful than expressions.") A quick Google of this blurb didn't turn up much useful information, but this seems to jive with Lynne's input above re: attributes.
• Data is not currently in SQL - it's in Access DB. We can migrate to SQL if necessary - that's one of the answers I'm supposed to be providing.
• The reason this is all currently being done in Word is because that's what the Sales & Engineering departments understand, and currently they're responsible for these docs. I'm sure this started out as a simple, nerdy solution to a small problem - some engineer didn't want to maintain two separate Word docs when he could create a database and then use mail merge to automagically build the same thing. Since then, it's grown to hundreds of tables and thousands of possible permutations.
• We already have FrameMaker installations in the department. If we can do this with FM11, great, but if not, no big deal - boss has already said he wants to move to FM12 as soon as possible. In other words, purchasing software - unless it's something additional needed to make all this work - isn't really a budgetary consideration.
• As mentioned, I have no skills with using FM for any kind of structured project, but I'm willing to learn if it seems like a good solution. Just need to figure out how to proceed.

Thanks for your input - looking forward to hearing what else you folks have to say.

[Arnis Gubins]

Another option to conisder is to look at database publishing tools like Miramo from Datazone (http://www.miramo.com) using their personal edition (a freebie) or PatternStream ($$). With Miramo, you can wrap the database content with tags and use either an XML/XSLT approach or Miramo's own internal macro processiong language (more Basic like) that creates formatted unstructured FM content. With Patternstream, you can pull database content directly into FM much like the mail merge approach.

[Guest]

Arnis - Both of those options (Miramo and Patternstream) answer at least one of my questions - namely, whether FM can/will integrate with a DB product. Apparently it will, so thanks for point those two solutions out. I haven't played with either of them enough to determine whether or how they'll solve my problem, but at least I'm moving in the right direction.

Alex - Part of my problem, I suspect, is that I know exactly squat about XML, including why I'd want to export it from Access. There don't seem to be many resources out there for Structured FrameMaker (like my excellent "Unstructured FrameMaker 11" book).

[Arnis Gubins]

Briefly, Miramo uses a push approach to get content into FM, while PatternStream is more of a pull approach. This will influence your workflow and how you interact with a database.

[Gorly]

Hi,

this presentation I just found may shed some light into the "why":

http://www.textmatters.com/resources/pdfs/struct_docs.pdf

-Alex

[Gorly]

Hi,

the line you love so much is the line that might rescue your day (more or less)

I checked if Access can do a XML export and - surprise - it can do.

You can do that export for almost everything in Access, means you could set up a form with all the database queries needed/wanted and export the result into XML.

Having an XML file at hand, you can import it into FM structured and get the result into whatever output format you need (be it HTML or PDF or whatever).

Alternatively you could automate that process and publish directly into PDF or HTML with XSLT and XSL:FO, but lose some typographic options on that route.

It is really hard to tell what's best for you - I'd suggest you get yourself involved with those possibilities and decide according to what you need in correlation to the effort needed.

And as Arnis already stated - there's always some place for 3rd party software, that might be able to do exactly what you need.

If you should want to use FM in the end, I would like to mention two things:

Don't bother with DITA or any other generalistic structure definition, if you don't really need to. They tend to complicate the process for such "small" projects.

While you're at it, you could evaluate, if it would be smart to move all of your documentation to structured FM (where the above mentioned structure definitions would kick in and become suitable). But I guess that's a bit far stretched for the moment

Either way, you will most probably end up getting involved with XML, DTDs (and structure in general), EDDs and the whole process of getting a set of structured information from application A to application B.

-Alex