Skip to main content

Author: Sarah O'Keefe

DITA Industry insights

Flare 5 DITA feature review, part 2

[Alan Pringle wrote most of this review.]

This post is Part 2 of our Flare 5 DITA feature review. Part 1 provides an overview and discusses localization and map files.

Cross-references and other links
I imported DITA content that contained three xref elements (I shortened the IDs below for readability):

  • Reference to another step in the same topic:
    <stepresult>
    Result of step. And here’s a reference to the <xref href=”task1.xml#task_8F2F9″ type=”li” format=”dita” scope=”local”>third step</xref>.
    </stepresult>
  • Reference to another topic:
    <stepresult>
    Result text. And here’s a link to the other task topic:
    <xref href=”task2.xml#task_8F2F94 type=”task” format=”dita” scope=”local”></xref>.
    </stepresult>
  • Link to web site:
    <cmd>
    Here’s another step. Here’s a link with external scope:
    <xref href=”https://scriptorium.com” scope=”external” format=”html”>www.scriptorium.com</xref>
    </cmd>

All three came across in the WebHelp I generated from Flare:


On the link to the topic, Flare applied a default cross-reference format that included the word “See” and the quotation marks around the topic’s name. You can modify the stylesheet for the Flare project to change that text and styling.

Relationship tables
DITA relationship tables let you avoid the drudgery of manually inserting (and managing!) related topic links. Based on the relationships you specify in the table, related topic links are generated in your output.

I imported a simple map file with a relationship table into Flare and created WebHelp. The output included the links to the related topics. I then tinkered with the project’s stylesheet and its language skin for English to change the default appearance and text of the heading for related concepts. The sentence-style capitalization and red text for “Related concepts” in the following screen shot reflect my modifications:

screen shot showing Related concepts heading in red and with sentence style capitalization
conrefs
DITA conrefs let you reuse chunks of content. I created a simple conref for a note and then imported the map file with one DITA file that contains the actual note and a second file that references the note via a conref.

Flare happily imported the information and turned the conref into a Flare snippet. It’s worth noting that the referencing, while equivalent, is not the same. In my source DITA files, I had this:

aardvark.xml contains:
<note id=””>Do not feed the animals

baboon.xml contains:
<note conref=”aardvark.xml#aardvark/nofeeding”>

Thus, we have two instances of the content in the DITA files — the original content and the content reference. In Flare, we end up with three instances — the snippet and two references to the snippet. In other words, Flare separates out the content being reused into a snippet and then references the snippet. This isn’t necessarily a bad thing, but it’s worth noting.

Specialization
Specialized content is not officially supported at this point. According to MadCap, it worked for some people in testing, but not for others. If you need to publish specialized DITA content through Flare, you might consider generalizing back to standard DITA first.

Conditional processing
When you import DITA content that contains attribute values, Flare creates condition tags based on those values. I imported a map file with a topic that used the audience attribute: one paragraph had that attribute set to user, and another had the attribute set to admin. When I looked in the Project Organizer at the conditions for the WebHelp target, conditions based on my audience values were listed:

audience.admin and audience.user conditionsI set Audience.admin to Exclude and Audience.user to Include, and then I created WebHelp. As expected, the output included the user-level paragraph and excluded the admin-level one.

DITA support level
Flare supports DITA v1.1.

Our verdict

If you’re looking for a path to browser-based help for your DITA content, you should consider the new version of Flare. Without a lot of effort, we were able to create WebHelp from imported DITA content. Flare handled DITA constructs (such as conrefs and relationship tables) without any problems in our testing. Our only quibble was with the TOC entries in the WebHelp (as mentioned in Part 1), and we’ve heard that MadCap will likely be addressing that issue in the future.

We didn’t evaluate how Flare handles DITA-to-PDF conversion. However, if the PDF process in Flare works as smoothly as the one for WebHelp, Flare could provide a compelling alternative to modifying the XSL-FO templates that come with the Open Toolkit or adopting one of the commercial FO solutions for rendering PDF output.

Sarah O'Keefe
June 17, 2009
Read More
DITA DITA-OT Industry insights

Flare 5 DITA feature review (Part 1: Overview and map files)

[Disclosure: Scriptorium is a Certified Flare Instructor.]
[Full disclosure: We’re also an Adobe Authorized Training Center, a JustSystems Services Partner, a founding member of TechComm Alliance, a North Carolina corporation, and a woman-owned business. Dog people outnumber cat people in our office. Can I start my post now?]

These days, most of our work uses XML and/or DITA as foundational technologies. As a result, our interest in help authoring tools such as Flare and RoboHelp has been muted. However, with the release of Flare 5, MadCap has added support for DITA. This review looks at the DITA features in the new product. (If you’re looking for a discussion of all the new features, I suggest you wander over to Paul Pehrson’s review. You might also read the official MadCap press release.)

The initial coverage reminds me a bit of this:

(My web site stats prove that you people are suckers for video. Also, I highly recommend TubeChop for extracting a portion of a YouTube video.)

Let’s take a look at the most important Flare/DITA integration pieces.

New output possibilities
After importing DITA content into Flare, you can publish to any of the output formats that Flare supports. Most important, in my opinion, is the option to publish cross-browser, cross-platform HTML-based help (“web help”) because the DITA Open Toolkit does not provide this output. We have created web help systems by customizing the Open Toolkit output, and that approach does make sense in certain situations, but the option to publish through Flare is appealing for several reasons:

  • Flare provides a default template for web help output (actually, three of them: WebHelp, WebHelp Plus, and WebHelp AIR)
  • Customizing Flare output is easier than configuring the Open Toolkit

I took some DITA files, opened them in Flare, made some minimal formatting changes, and published to WebHelp. The result is shown here:

Sample WebHelp from DITA through FlareNot bad at all for 10 minutes’ work. I added the owl logo and scriptorium.com in the header, changed the default font to sans-serif, and made the heading purple. Tweaking CSS in Flare’s visual editor is straightforward, and changes automatically cascade (sorry) across all the project files.

Ease of configuration
Flare wins. Next topic. (Don’t believe me? Read the DITA Open Toolkit User Guide — actually, just skim the table of contents.)

Language support
The Open Toolkit wins on volume and for right-to-left languages; Flare wins on easy configuration (I’m detecting a theme here.)

Out of the box, both Flare and the Open Toolkit provide strings (that is, localized output for interface elements such as the “Table of Contents” label) for simplified and traditional Chinese, Danish, Dutch, English, Finnish, French, German, Italian, Japanese, Korean, Norwegian, Portugese, Spanish, Swedish, and Thai (I have omitted variations such as Canadian French).

Beyond that, we have the following:

  • Right-to-left language support: Only in the Open Toolkit
  • Language strings provided by the Open Toolkit but not by Flare: Arabic, Belarusian, Bulgarian, Catalan, Czech, Greek, Estonian, Hebrew, Croatian, Hungarian, Icelandic, Latvian, Lithuanian, Macedonian, Polish, Romanian, Russian, Slovak, Slovenian, Serbian, Turkish, and Ukrainian
  • Ease of adding support for a new language: Flare wins. In the Open Toolkit, you modify an XML file; in Flare, you use the Language Skin Editor (although it looks as though you could choose to modify the resource file directory directly if you really wanted to)

Thus, if you need Hebrew or Arabic publishing, you can’t use Flare. The Open Toolkit also provides default support for more languages.

Map files
I imported a map file into Flare and published. Then, I changed the map file to include a simple nested ditamap. Here is what I found:

  • Flare recognized the map file and the nested map file and built TOC files in Flare with the correct relationships.
  • Inexplicably, the nested map file was designated the primary TOC. I speculate that this might be because the nested map file was first in alphabetical order. I changed the parent map file to be the primary TOC to fix this. I don’t know what would happen for a more complex set of maps, but I am concerned.
  • Flare inserted an extra layer into the output TOC where the nested map is found.
  • The titles generated in the TOC are different in Flare than they are through the DITA Open Toolkit (see below).

I generated the output for my map file (the nested map is the “The decision to implement” section in this screen shot) through the DITA Open Toolkit and got the following XHTML output:
Then, I imported the same map file into Flare, generated WebHelp, and got the following TOC output:

Notice that:

    • The TOC text is different (!!). The DITA Open Toolkit uses the text of the topic titles from inside the topic files. Flare uses the text of the @navtitle attribute in the map file. My topic titles and @navtitles don’t match because I created the map file, then changed a bunch of topic titles. The map file didn’t keep up with the new titles (because it doesn’t matter in the Open Toolkit), but it appears to matter for Flare. The entry in the map file for the first item is:

&lt;topicref href="introduction.xml" navtitle="Introduction" type="topic"&gt;

Flare picks up the “Introduction” from the navtitle attribute.

Inside the file, you find:

&lt;title&gt;Executive summary&lt;/title&gt;

The Open Toolkit uses the content of the title element from inside the file.

  • The Implementation section has added an extra layer in the Flare output. It appears that nesting a map file results in an extra level of hierarchy.

The inconsistency between the two implementations is annoying.

In part 2 of this review (coming soon), I’ll look at cross-references, reltables, conrefs, specialization, and conditional processing.

Sarah O'Keefe
June 12, 2009
Read More
Webinar

Webinar mania!

I have several webinar-related updates to share:

Next week, the State of Structure

You probably know that Scriptorium conducted an industry survey on structured authoring earlier this year. The report, The State of Structure in Technical Communication, is available in our online store for $200.

There is a cheaper option to get the highlights. On Tuesday, June 16, at 1 p.m. Eastern time, I’ll be delivering a one-hour webinar that highlights the most important findings.

Coming in July and August

Expect to see additional webinars in cooperation with our TechComm Alliance partners, Cherryleaf and HyperWrite. We are also welcoming Jack Molisani of ProSpring, who will offer excellent and candid career development advice. Watch this space for details about these upcoming events. Scriptorium consultants will also be offering additional content.

Recorded events

Two of our recent webinars are now available for download:

  • Hacking the DITA Open Toolkit
  • Documentation as Conversation

Each webinar lasts about one hour and is $20, either live or recorded. You can register for the Tuesday webcast and download recordings in our online store.

(Warning: The recorded webcast files are quite large.)

Sarah O'Keefe
June 9, 2009
Read More
Food & fun

More cowbell!

About a year ago, we added Google Analytics to our web site. I have done some research to see what posts were the most popular in the past year:

  1. The clear winner was our FrameMaker 9 review. With 21 comments, I think it was also the most heavily commented post. Interestingly, the post itself is little more than a pointer to the PDF file that contains the actual review.
  2. InDesign CS4 = Hannibal post, which discussed InDesign’s encroachment on traditional FrameMaker features.
  3. A surprise…a post from 2006 in which Mark Baker discussed the merits (or lack thereof) of DITA in To DITA or not to DITA

Our readers appear to like clever headlines, because I don’t think the content quality explains the high numbers for posts such as:

We noticed this pattern recently, when a carefully crafted, meticulously written post was ignored in favor of a throwaway post dashed off in minutes with a catchy title (Death to Recipes!).

For useful, thoughtful advice on blogging, I refer you to Tom Johnson and Rich Maggiani. I, however, have a new set of blogging recommendations:

  1. Write catchy titles
  2. Have an opinion, preferably an outrageous one
  3. More cowbell

Sarah O'Keefe
June 4, 2009
Read More
Localization

Think global

All your docs are belong to us.
We are joining with a couple of other technical communication companies to form the TechComm Alliance:

Three companies—Cherryleaf Ltd., HyperWrite, and Scriptorium Publishing—are forming TechComm Alliance to help us handle technical communication projects around the world. We are located in the United Kingdom, Australia, and the United States, respectively, and each company has customers in both its home location and in other countries. TechComm Alliance will make it easier to work with global companies that need services worldwide.

How will this work? We expect to:

  • Work together on large projects that require support in multiple locations. For instance, Scriptorium might be implementing structured authoring for a U.S. company that also has operations in Europe and Australia. During rollout, instead of sending a Scriptorium consultant around the world, we partner with Cherryleaf for the training in Europe and with HyperWrite for the training in Australia. The result? Our customer saves on travel expenses, and our consultants spend less time in airplanes.
  • Refer projects to each other. Each company has (and will continue to have) clients around the world. When we feel that a local presence would benefit the customer, we can refer the project to our alliance partners.
  • Produce webinars and other events together. I’d like for Scriptorium customers to benefit from the expertise of our partners, and we are working on joint webinars.

Sarah O'Keefe
May 26, 2009
Read More
Webinar

Documentation as conversation webinar

We have added Documentation as Conversation, presented by Anne Gentle, to our upcoming webinars. Anne is scheduled to present on June 9 at 11 a.m. Eastern time:

Even if your documentation system does not converse with your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well or learn something new as if they were in a classroom with a community for classmates. This talk describes how you can think about documentation and user assistance in a conversational way, with the help of social media technology. I’ll discuss the topics in my new book, Conversation and Community: The Social Web for Documentation. I’ll describe the use of in-person Book Sprints that combine wikis and community events to gather together writers to accomplish documentation goals

Anne is an expert, perhaps the expert, on using wikis and other social media to extend traditional documentation efforts. She’s also an excellent speaker, so I hope you’ll join us for this session.

Register for Documentation as Conversation ($20)

See all upcoming webinars

PS We are working on additional topics and looking for more speakers. Do you have topics you would like us to cover? Please let us know. We are working on a couple of sessions on document conversion.

Reblog this post [with Zemanta]

Sarah O'Keefe
May 22, 2009
Read More
DITA DITA XML—authors Food & fun

Death to Recipes!

I love food. I enjoy cooking and I especially enjoy eating. One of my favorite web sites is epicurious.com, and the kitchen shelf devoted to cookbooks sags alarmingly. Many Saturday mornings, you will find me here.

But I am not happy about how recipes have insinuated themselves into my work life. For some reason, the recipe is the default example of structured content. Look at what happens when you search Google for xml recipe example. Recipes are everywhere, not unlike high fructose corn syrup. Unfortunately, I am not immune to the XML recipe infiltration myself.

I understand the appeal. Recipes are:

  • highly structured content
  • well understood

But I think the example is getting a little tired and wilted. Let’s try working with something new. Try out a new kind of lettuce, er, example. This week, I’m trying to write a very basic introduction to structured authoring, and I’m paralyzed by my inability to think of any non-recipe examples.

I’m considering using a glossary as an example. After all, it’s a highly structure piece of content whose organization is well understood. Maybe I’ll use food items as my glossary entries. Baby steps…

PS It’s totally unrelated, but this article about two chefs eating their way through Durham (“nine restaurants in one night, at least five hours of eating and drinking”) is quite fun.

Sarah O'Keefe
May 19, 2009
Read More
DITA DITA-OT Industry insights

DocTrain’s demise and a challenge to presenters

Unfortunate news in my inbox this morning:

I regret to announce that DocTrain DITA Indianapolis is cancelled. DocTrain/PUBSNET Inc is shutting down.

As a business owner, messages like this strike fear in my heart. If it could happen to them…gulp. (This might be a good time to mention that we are ALWAYS looking for projects, so send them on over, please.) My condolences to the principals at DocTrain.

Meanwhile, I’m also thinking about what we can do in place of the event. I had a couple of presentations scheduled for DocTrain DITA, and Simon Bate was planning a day-long workshop on DITA Open Toolkit configuration.

So, here’s the plan. We are going to offer a couple of webinars based on the sessions we were planning to do at DocTrain DITA:

Each webinar is $20. We may record the webinars and make the recordings available later, but I’m not making any promises. Registration is limited to 50 people.

Here’s the challenge part: If you were scheduled to present at DocTrain DITA (or weren’t but have something useful to say), please set up a webcast of your presentation. It would be ultra-cool if we could replicate the event online (I know that the first week in June was cleared on your schedule!), but let’s get as much of this content as possible available. If you do not have a way to offer a webinar, let me know, and I’ll work with you to host it through Scriptorium.

And here’s my challenge to those of you who like to attend conferences: Please consider supporting these online events. If $20 is truly more than you can afford, contact me.

Sarah O'Keefe
May 18, 2009
Read More
Localization Structured content

Building efficient multilingual workflows

STC Intercom, April 2009

A common argument for XML-based workflows is that they automate production and localization tasks. With XML, localization can be reduced to a fraction of its original cost, but how exactly does that happen?

Sarah explores automization in localization and two technology standards used in multilingual workflows: The Extensible Stylesheet Language (XSL) and XML Localization Interchange File Format (XLIFF).

Download the PDF PDF file (125 K)

Sarah O'Keefe
April 30, 2009
Read More
DITA

DITA adoption increasing overall structured authoring adoption

I’m knee-deep in survey data analysis. With over 600 responses, our recent structured authoring survey was hugely successful–thank you. Many respondents added candid details about their experiences with structured authoring implementation–their fears, mistakes, and biggest surprises.

The survey report will be available later this month (free to participants, $200 for others), but I wanted to give you a couple of preliminary highlights:

  • About 30 percent of respondents said that they are currently using structured authoring.
  • There’s a lot of hype around DITA, but our data indicates that it’s backed up by reality. Consider this chart, which shows the top three types of structure (custom, DocBook, or DITA) implemented, being implemented, or planned.

DITA accounts for the vast majority of structure implementations--past, present, and futureDITA dominates the chart. But it looks as though DITA is additive. That is, it’s not cannibalizing the numbers for DocBook or custom structures. Those numbers are relatively flat. Instead, it looks as though DITA is increasing the total number of implementations.

If you are attending the STC Summit this year, I’m doing a presentation on the survey results on Monday, May 4, at 1:30 p.m., called “The State of Structure.”

Sarah O'Keefe
March 30, 2009
Read More