just write click

1. Content is king. Your source content can be Word, Frame, or DITA. You can even import convert other formats such as RoboHelp to Word or Frame and go from there.
2. Formats are separate from content and can be customized.
3. Combining content is allowed and even encouraged. Mixed content is just fine.
4. There are great demos (over an hour’s worth) on the Quadralay web site.
5. ePublisher has an extendable XML adapter. This extensibility means that no matter what XML you’re putting in, ePublisher can be extended to understand it.
6. You can automate the dickens out of your output build processes and integrate with development’s version control systems and build with the Auto-mapper.
7. The WebWorks Wiki (uses MoinMoin engine if you’re wondering) has lots of information and they encourage people to contribute to it.

I’m attending as many sessions as I can at the Quadralay WebWorks User Conference - called the WebWorks RoundUp. Right now I’m listening to a great demo using WebWorks to publish Word or Frame source files to wikitext.

Start with WIF

The WebWorks wiki defines WIF as WebWorks Intermediate Format - basically their Document Type Definition. Serendipitous search engine love for WebWorks. I hadn’t realized that when you Google “WIF” you’ll find there is a lot of academic call for the Wiki Interchange Format - a lowest common denominator of wiki content exchange. WIF defines a subset of XHTML as an over-the-wire format for wiki content exchange.

Keep it simple

He’s demonstrating the concept with headings and paragraphs only, but I would imagine that ordered and unordered lists would be simple, even nested indented lists are simple enough to mark up.

No tables, and I’ll admit, they’re a nightmare to markup in wikitext, so I sure wouldn’t tackle writing the XSLT to create tables from XML to wikitext.

Graphics you could create the wikitext for the file reference, as long as you take the time to upload the graphics to the location where the wiki is expecting them.

Generate the wikitext

He’s generating wiki markup using XSLT transforms that he has already set up.

Wikitext markup is really simple, using ASCII characters such as == heading text == to mark up a heading. In this example markup, more equals signs surrounding the heading indicate a deeper nesting of headings. Two equals signs indicate a heading 2, three === indicates a heading 3. Paragraphs are often not marked up at all, making them the simplest output of all. Refer to the wikimatrix.org’s markup comparison tool for more examples.

I would have liked to see examples of links and image references created, but this was an hour demo after all.

Put wikitext into your wiki

Finally, he’s copying and pasting the marked up wikitext into his wiki. For a long article where one page is one article, this approach makes a lot of sense. I could use a tool like this for the One Laptop Per Child project, where we have a Simplified user guide all in one wiki page. Each section is editable just because the wikitext is marked up using ==section name==, which is the markup for that particular wiki (MediaWiki).

And in his keynote the following day, Ben Allums demonstrated that he could publish to the wiki itself. Now THAT is an exciting development. I’ll dig deeper into the guts of that and report back.

Scenarios for converting to wikitext

I can think of plenty of scenarios for using this conversion process. Let’s say you need a hundred page user manual put into wiki format. This type of conversion would give you a huge leg up on the pre-population of a wiki with a user guide that is already in FrameMaker or Word. I would imagine you could somehow automate the webform population. For example, use IBM’s freely available CoScriptor to record the process where you create a new wiki page, then just run the CoScriptor script and paste when needed, then run another script that renames the new wiki page.

Because you can also publish directly to the wiki, but it seems to be in a way that doesn’t touch what’s already there, this method is a great way to continually update your wiki with fresh content.

Another great use of creating wikis with a conversion process would be for API documentation, especially if you already had a large body of work in a wiki. Let’s say you’re using DITA as your source file for your API, convert new portions to wikitext.

Any other scenarios for this conversion tool?

Adobe has announced a Technical Communication Suite, combining FrameMaker, RoboHelp, Captivate, Acrobat 3D, and Flash, available in October 2007 for $1599 or $999 upgrade pricing if you already own one of the tools. This price point is well below what buying those products individually would cost (compare to $3600). I’m about a day late to the flurry of blog posts, as there are many bloggers commenting on this release, but many of them are focusing on the FrameMaker to RoboHelp single sourcing aspect, including the Adobe Technical Communication blog.

Scott Abel, The Content Wrangler, noted the price temptations, especially for people currently on RoboHelp. I’d just add that the upgrade price is the same price as Adobe Creative Suite 3 Web Standard ($999).
Dan Ortega’s message from Astoria appears to be but there’s no enterprise workflow and it’s a desktop solution, meaning, tech writers will still be the only users in a company using FrameMaker. Charles Jeter notes the same lack of collaboration in the suite in a nice wrap up post as well.

Sarah O’Keefe notes that most of her clients are going lighterweight than FrameMaker for their XML solutions.

Bill Swallow (techcommdood) notices that you can only go from Frame to RoboHelp, not back.

While single sourcing is always interesting to me, what I’m curious about are the use cases for Captivate, Acrobat 3D, and Flash, when using this Suite. I’ve used FrameMaker and RoboHelp in the past, but haven’t gone beyond the trial version of Captivate. So I looked at the webinar listing and there are hints at use cases that are an interesting sweet spot for the technical writer who wants to move past the static manual into interactive user assistance - not to mention the technical trainers looking for the correct tool to build interactive demos. Here are some catch phrases I lifted that might be just marketing-speak, but also might speak to where our profession is headed.

• track help system usage
• leverage existing content to create interactive help or performance support
• question randomization
• animation imports from PowerPoint
• do this cool buzzword stuff… without the help of your engineering department

So perhaps a key aspect of what Adobe has heard from tech writers all over is, we want to do cool stuff, but we’re not getting the resources we need to program the cool stuff.

And indeed, the webinar folks seem to want to help define where we’re headed and how we’ll get there. To quote from the intro paragraph, “What does this mean for technical communicators, instructional designers and eLearning professional today and tomorrow?” As go the toolset, so goes the career? I suppose that the skill demand certainly shapes what you learn as a technical communicator in order to stay employable. Does your software toolset make you do your job a certain way?

FrameMaker 8 was released yesterday, with DITA possibility built in, but you will need to do your homework to determine the best path to migrate legacy content from unstructured Frame to DITA. Questions such as Unstructured to DITA - Concise Conversion Information Needed and What are the steps to convert an FM book to DITA To CHM? are consistently appearing on the Adobe Framemaker 7.2 application pack forum. While conversion is part of the migration process, you have to examine your content and get it to a point where it could be converted, so I prefer the term migration to conversion.

I did some research on this topic, attempting a conversion of legacy unstructured Framemaker content to DITA, and wanted to write it up here in case it helps others.

In my experience with Frame 7.2, I wasn’t able to complete the entire complex process, partially due to the unstructured Frame files, partially due to my limitations in getting XSL to work through Framemaker and writing a Framemaker structured application. Feel free to comment on these instructions if you have questions or ideas for where this process may not work well. Note that I haven’t fully studied how this process might change with the introduction of Frame 8, although many of these tips and tricks will still be useful for preparing your content.

Content preparation tips and tricks

If your Frame content is not already written in topics and pretty well structured, work really hard on getting the legacy content into some sort of order that will help in conversion. For example, make each Heading a topic starting point. Next, you may want to type the content into task, concept, reference beforehand using style tags to indicate what type of topic the content is, such as heading1task, heading1concept.

Indicate your task step numbered lists with a different style name from “plain” numbered lists.

Write your abstract and shortdesc (short descriptions) as initial paragraphs of each topic.

Use test Frame files that have few paragraph tags used. Add in paragraph styles one at a time and test the step-by-step process to make debugging easier.

Use a subset of DITA tags for your conversion, meaning you will be converting content to topics with fewer tags than the full DITA tag set. After conversion you can re-tag the content more specifically but having fewer tags to go to means less troubleshooting for the conversion itself.

Performing the conversion

The overall steps for the conversion involve the following tasks:
1. Structure the current unstructured FrameMaker document with the conversion table and rules text file as mapping helpers.
2. Open Frame book file and import the EDD or Element Definition Document, a proprietary FrameMaker file that correlates to a DTD (Document Type Definition).
3. Save the new resulting file as XML, either using a customized migration structured application that applies custom XSLT, or using the DITA Application Plug-In (which is a structured application also).

Each overall step is described in the tasks below.

I’ll also describe the files you’d create to start such a conversion. To create a structured application, you create a new folder in a C:\Program Files\Adobe\FrameMaker7.2\Structure\xml\ directory. This folder contains:

• A text file that tells FrameMaker what XML means in it’s own formatting conventions. For example, it tells Frame that the “xref” element is a cross-reference in FrameMaker.
• A Document Type Definition file that works in concert with the EDD file that FrameMaker needs to interpret the DTD.
• An Element Definition Document required by FrameMaker. This file is what you import into a FrameMaker chapter file.
• An XSL file that could transform FrameMaker XML into separate DITA topics rather than maintaining many topics in each chapter file, instead each topic would be in its own file.
• A structured FrameMaker file containing the configuration information for both the DITA plug-in and the new structured application that could use the XSL file for transformations.

To apply the conversion table

1. Open the Frame book file that has had the EDD imported into each chapter file.
2. Open the conversion table file.
3. Click File->Utilities->Structure Current Document.
4. Select the conversion table file name from the drop-down list, and then click Add Structure.

To apply the EDD

1. Open the Frame book file and select all chapter files using Shift+click.
2. Click File->Import->Element Definitions.
3. Select the EDD file name and click Import.

To save as XML

1. Click File->Choose Structured Application. Select either the trx-migrate structured application or the DITA-Topic-FM structured application.
2. Open the Frame book file and select all chapter files.
3. Click File->Save As and choose XML.
4. If you are using the trx-migrate application, the XSLT would be run on this step. If you are simply saving as DITA XML, then you would choose DITA as the Structured Application from the File menu.

Comments on the conversion table

The conversion table takes existing content and maps each paragraph and character style to an XML element, then wraps the elements in outer elements as needed. To accurately portray the information and ensure that one change doesn’t affect other areas of content, you must modify this table one element at a time and then check for accuracy. The conversion table is a painstaking and time consuming project in itself, depending on the complexity of the content you have to start.

Manual cleanup and DITA map creation

According to this article, you would have additional manual cleanup of graphic importing, copy and paste for all table cell text, creation of cross reference links, and creating the hierarchy for your DITA maps because of the flattened nature of the saving topics at the heading level.

Reading list and references for conversion

• Migrating from Unstructed to Structured FrameMaker white paper
• Appendix A in the Structure Application Developer’s Guide Online Manual
• Using XSLT in Adobe FrameMaker 7.2 technical paper
• DITA Language Reference included in the DITA Open Toolkit download page at sourceforge.net
• Integrating DITA at Idiom Technologies article on Bright Path Solution’s web site

While on maternity leave, I read through the lengthy and informative What’s New in Adobe RoboHelp 6? even though I don’t use RoboHelp. I like to follow Adobe’s treatment of tech pub tools though.

I suppose if I had to pick favorite new features, one would be the Command line compiling for help projects. I do love batch files, and scheduling help builds automatically would be great.

I especially love Rob’s “Emotional Comments” paragraph towards the end of the review. To quote: “Like many of you, I have had my ups and downs with RoboHelp. I’ve enjoyed working with the tool for a long time. (Well, at least since they worked out most of the bugs in the first seven releases.) I was surprised and disappointed at the complete lack of interest demonstrated to our industry by Macromedia. And I remain cautiously optimistic that Adobe will invigorate the technical communication community with its newly created suite of tools (which include RoboHelp, Framemaker, Captivate, and Acrobat).”

This paragraph is actually the first mention I’ve read of the “newly created suite” of tools. I must go to the Adobe site now and read up on it… Okay, a quick Google search didn’t bring me to the Adobe site but brought me to the blog entries that speculate about such a suite. However, on the Adobe products page, there is a category for eLearning and technical communication products which is an excellent collection of tools.

I’ve also added the Adobe Technical Communication blog to my feed reader, a group blog where they’re keeping the rumors and speculation at bay by simply blogging about it. Way to go, Adobe. This blog is an excellent example ofhaving your product managers use a Web 2.0 communication tool like a blog to field questions and allay concerns.

I’ll speculate freely about whether Adobe’s working on a tech writer workflow or toolkit, bouncing off of The Content Wrangler’s prediction of a Technical Writing Suite from Adobe. (Thanks for the trackback enablement, Scott Abel!) And what a cool concept, a suite of tools that work together to help us tech writers, similar to Adobe’s Creative Suite. If the creatives can get such a bundle, why not the technical writers as well?

Here’s an interesting article and interview about Adobe’s newly sparked interest in RoboHelp. My favorite quote from this article has to be:

“But if Adobe truly intends to market an authoring tool called RoboHelp in 2007, it faces at least two challenges-in the user base and the code base. Macromedia’s stewardship did little to improve the RoboHelp technology-its aging kadov-laced HTML editor, the tack-on functions (some 12 years old) and a WebHelp output that’s like the bumblebee: it’s a miracle it flies. And as for the users-we know that story from several directions. ” from David Locke, WordSmith LLC.

Last week I attended the Benefits of Structured Authoring and Migrating in Preparation for XML webinar from Adobe (and played the Yeti batting a penguin Flash game while waiting for the presentation to start, a.k.a Pingu Throw). In it the presenter mentioned a DITA plug-in for FrameMaker (as well as other plug-ins, even though he said you can do all the XML authoring you want to with just FrameMaker. He probably should have qualified that as “FrameMaker plus plug-ins.”) Today’s seminar starts in about a half hour and it’s titled “FrameMaker and DITA” ( register here).

My take? Give us the tools and we’ll build some cool information systems. What do you think about bundled software systems geared towards a specific user base?

Jen Linton, the co-author of Introduction to DITA:Getting Started with the Darwin Information Typing Architecture is in Austin to teach the DITA Getting Started workshop hosted by BMC Software. I’m attending along with several of my co-workers, and we’re all learning a lot.

Last night I went to dinner with Don Day, chair of the OASIS DITA Technical Committee, Jen, and Wendy Shepperd, a manager here at BMC. Jen asked Don, “What’s the story with the bird in the DITA logo?” I had blogged earlier that it’s a finch with a specialized beak, but it turns out there’s more to the story. Don explained that it’s a woodpecker finch, one of the finches Darwin documented from the Galapagos Islands, and it’s a tool-using animal. Woodpecker finches pluck the spines from cacti or use wooden splinters to extract grubs and other bugs from holes that their beaks don’t fit for a tasty meal. That’s a fun piece of trivia. Here’s the logo to which I’m referring.

After dinner we went to the Central Texas DITA User Group meeting, where Jen told and showed us how she assembled the Introduction to DITA book using DITA topics. The most interesting part for me was to learn about the Mekon FrameMaker plug-in that lets you import DITA content into FrameMaker for book assembly and above all, index generation. Nifty! It’s part of the DITA Open Toolkit if you browse the CVS repository.

In our training class, we wondered out loud where all the local User Groups are forming currently, and I found this list at http://dita.xml.org/user-groups:

Canada

• Ontario: Toronto DITA User Group
• British Columbia: Vancouver DITA User Group

United States

• California: Silicon Valley DITA Interest Group
• Indiana: Indy DITA
• Massachusetts: Boston DITA User Group
• New York: NY Metro DITA Users Group
• North Carolina: Research Triangle Park DUG
• Texas: Central Texas DITA Users Group (Austin)