Anybody using Flare with DITA?

[wbrisett]

I recently ran across yet another bug in Flare, this time with the DITA export. I find this bug very odd because it was very obvious. Then I began to wonder if anybody is really using Flare to generate DITA content. There isn't even a sub-forum for DITA, but there is for just about every other target type.

Anybody using Flare to edit DITA?

If you are, I'd be curious to know if only part of your group is using Flare. I know of at least one or two companies that are using both FrameMaker and Flare for generating DITA, but need to find out more about how they are living with that option. We're having discussions in-house about trying to use different DITA authoring tools and since we own a couple licenses for Flare, we're trying it out, but I had to write a script to fix the DITA output from Flare, so it would work seamlessly. I'm not sure what other issues will crop up and I'm curious to learn what issues other might have encountered.

Wayne

[RamonS]

While DITA has its place and use, my guess is that the majority of Flare users doesn't use it. The concepts and structures are likely to be found in most help projects, but it isn't intended the DITA way, nor is DITA a target.
What exactly is the problem that you encountered? Did you report it? Did you contact support?

[wbrisett]

The issue is the incoming DITA isn't the same as the outgoing DITA, and yes it was reported and confirmed by Madcap as a bug.


Incoming DITA looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "$STRUCTDIR\xml\DITA\app\dtd\ditabase.dtd">
<reference id="v5464513">
<title id="v481211">Start Conditions</title>
<refbody id="v481213">
<section id="id0964B900KUI">
<p id="v5464525">The start condition mechanism is a unique…

The issue happens during the DITA export from Flare:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="v5464513">
<title>Start Conditions</title>
<refbody>
<section id="v481213">
<p id="v481211">Start Conditions</p>
<section id="id0964B900KUI">
<p id="v5464525">The start condition mechanism is a unique…


The title ID and Refbody ID are put into section and paragraph tags that don’t belong.


I've written a script to fix this, but since I doubt many people are using Flare for DITA, like all my bugs, I suspect this one won't get any air by Madcap.

[jcoria]

I hope it does get "air". DITA is a great content structure model.

[wbrisett]

I did have a conversation with Madcap today about the handful of tickets I have open. The good news is that engineering is aware of them, there just isn't any ETA on when any of them will get fixed.

I think the hardest thing really is convincing the DITA community that Flare can be used as a DITA editor. But the reality is most wouldn't ever consider it a DITA tool since you aren't doing things in XML. I've sent emails to a couple of individuals that posted on the DITA groups I'm subscribed to, who are using both Flare and FrameMaker in-house for DITA. I was hoping to find more people who might be using it that way here. However, it doesn't look promising. I will say that one of DITA's strengths and weaknesses is its structure. The problem with DITA is that it is SO rigid that at times you're forced to do some pretty silly things to do what Flare and other tools can do because they aren't limited by the DITA constructs. However, there are also times when forcing people into a very rigid structure works to your advantage, such as times when you want consistency. I really was hoping that since Madcap joined the Oasis board that there might be a bigger push into the DITA community with Flare, but so far that hasn't happened. We'll see, I do have some hope, just not tons.

Wayne

[RamonS]

I think the best would be to use DITA as structure model without using the DITA format. The concept of DITA in regards to structuring documentation is excellent. The problems arise when dealing with the second aspect of DITA being a (file) format that is suitable for exchange. The DITA format faces the same issues like any other rigid system. I think those who want to use DITA do that for the reason of content exchange. Otherwise I don't see any point to suiting the DITA way of doing things if there are no consumers for the documents on any other end.
That said, I think MadCap needs to fix these issues (and many others) before adding yet another big feature. I am sure MadCap has an ETA set internally, they just don't want to make this public as this generates expectations which then have to be met.

[GregStenhouse]

I've used DITA from Flare in a test project. Like you I had a few issues with the output (in my case, generating errors from the open toolkit). And like you I had to write scripts to get around those issues.

One of them was support for note types. Also problems from memory with conditional tagging, the syntax of the ditamap file, and list structure (especially nested steps and paragraphs).

It would be better if Flare supported DITA authoring (so you could see as you write whether things are valid or not), and this was on Madcap's radar when they first talked about DITA, but I've been told this may be a some time away (if ever). Mainly due to the low uptake of Flare DITA (which may be because of the limited features or bugs? it appears you need people to use it to fix/enhance it, but people won't use it until it's fixed/enhanced!)

In summary, you can work around the issues, but it doesn't really make the current version of Flare a useful out of the box solution for DITA export.

Cheers
Greg

[forfear]

Found this discussion helpful.

Heard about the earthquakes in ChristChurch on the news, just.

[3lliot]

I've just started a new job, they have quite a lot of existing documentation - I plan to migrate it all to Flare, but I'd like to stick to a DITA structure, mainly because it's a logical approach, not really because I want to future-proof it for any DITA-based editing or publishing environments.

So - could anybody recommend a good approach for implementing the DITA structure in Flare? other than just keeping the DITA structure in mind, and consciously authoring things that way?

Ideally I'd like to know if there was some way I could funnel my authoring in that direction. For example, linking to a DTD or schema which would flag non-DITA structure.

cheers
-Elliot

[wbrisett]

Elliot:

That's really not how Flare works. You can only force a DITA structure on Flare by thinking in DITA and working that way in Flare. However, you're the gatekeeper, not the tool itself. There is nothing wrong with simply writing in topics and focusing in on the structure as they do in DITA with three main categories:

• concept
  reference
  task

There is also the generic topic, but rarely does something go into that group (at least in my experience). The reference group tends to be the catch all for what I do (hardware documentation).

Most of the things you really want to do in DITA, Flare does. It simply does them in a slightly different way and doesn't handcuff you with the structure. So, if you want to break things a bit, you can. But Flare's strength is topic-based authoring which at the end of the day is really what you want to do with DITA.

I'm curious, is there something other than portability that makes you want to "force" the DITA DTD onto Flare? I might be missing the point, and just want to make sure I've covered things here.

Wayne

[RamonS]

I think Elliot is more interested in "DITA - The Concept" rather than "DITA - The File Structure". As far as the concept goes, it makes perfect sense and is a very good way to organize content. The file structure is yet another XML based document type definition. As far as the tool (Flare) is concerned, the tool should be able to make DITA DTD conforming files any time. Of course, it makes more sense if the writer adheres to the concept.
As far as finding non-DITA structures, I don't think that a tool can do that. It is up to you to associate a topic with a category and as with everything, you make a decision and someone will think it is wrong. In some cases it is up to interpretation as to where concept content ends and task content starts. You could set up some guidelines for yourself. For example, when you have a topic that contains descriptions of components and step-by-step instructions you may need to separate the descriptions (concept or reference) from the instructions (task).
That said, these three categories are the traditional DITA categories, but DITA is intentionally designed for allowing the writer to add more categories when necessary. Maybe you have a lot of technical drawings in the docs or want to add screen movies, which could be considered concept, reference, and task and might be worthwhile to have their own category.
Elliot, don't think too much about structure meaning how the file is formatted internally (you mentioned that this isn't your main goal anyway), but focus on sticking to the concept. You should do fine when transitioning.

[3lliot]

Thanks guys.

I used to work in Arbortext a lot, which is why I was wondering if you could point Flare at a DTD.

I'll just have to parse my brain using a virtual DTD & hope what comes out at the other end is vaguely compliant. I am more interested in the information typing than the actual file structure, so I guess if I remember to modularise my content properly, that's half the battle won.

-E

[forfear]

Thanks guys.

I used to work in Arbortext a lot, which is why I was wondering if you could point Flare at a DTD.

I'll just have to parse my brain using a virtual DTD & hope what comes out at the other end is vaguely compliant. I am more interested in the information typing than the actual file structure, so I guess if I remember to modularise my content properly, that's half the battle won.

-E

I've posted a feature request for more native support of DITA. Its great the authors familiar with DITA are pointing out irregularities in Flare's DITA output.
I think for Flare to support a more extensible DITA environment is support the model as a separate authoring mode - this would open the gates such as DTD support, more robust transforms, and allowing the DITA irregularities to be fixed at a much deeper level than the current 'DITA as just one output target' allows.

It would be like taking potshots at a target with a pea shooter. thoughts?

[RamonS]

Thoughts? Yea, DITA technology in Flare needs some fixing, but the real value in DITA is the concept behind it. The technical stuff such as DTD, proper formatting and so on are not unimportant, but I think one gets a lot of good things from DITA by following the concept and using Flare for any output. One could argue that for example WebHelp is just another form of DITA based output, but the DITA file format is mainly intended to bridge the gap between diverse systems. That said, unless you take Flare's DITA output and then do something else with it you don't need the DITA output.
DITA has its place and use, but DITA is like SharePoint, "the cloud" (formerly known as web applications), or the iPhone. There is some use to it and it is nice that people have access to it, but the hype is nothing more than a fad. Only a fraction of those cases I came across where people insisted on DITA file format only did so because it sounded good. In the end they didn't do shniggs with it. Like spending tons of money to "transition to SharePoint" and then serve up only static web pages.
For Flare it would make sense to get the DITA output into a shape that works with the Open Toolkit and that way it is no longer a problem to make output formats such as Java help or Eclipse help. Would be nice if people don't have to fork around on the command line.

[wbrisett]

Ramon, my only comment on your thoughts is that recently we have found the ideal situation where DITA is going to be helpful. That is, we sold off one part of our company. The other company who bought it isn't using any of the same tools we did. However, they are using DITA and we're finding that the transition of the data from one system to another is turning out to be much easier than anybody (myself included) thought it would be. I'm also not sure I agree with your assessment that DITA is a fad. However, I'm not sure it's growth rate is going to skyrocket. It will simply be one of the many structured environments people can work in. Although, if you follow any of the STC articles and papers, you would think that if you're not using DITA you're way behind the times, and I suspect that may be where some of the ideas of it being over-hyped come from.

But, you're right. At times I feel very handcuffed dealing with the restrictions of DITA, which is why I agree with you that as a concept it is exactly what people need to be doing. Thinking of things as chunks of information. However, one of my pet peeves about the DITA community as a whole is they have adopted that message to the extreme. The DITA spec certainly looks better now (v1.2) than it did in previous versions, but it certainly isn't a shining example of DITA output that you could take to a group of people and sell the idea of going into DITA with. The community at times has lost the fact that information layout is as important as the information itself at times. Wall-to-wall text on a page while technically accurate isn't the ideal way to learn. And certainly dealing with the Open Toolkit, XSL-FO and the various things you have to do to render DITA outside of tools like Flare make it much harder to implement an output that presents information in a way that makes learning the information easy.

That said, there are times that I would love to use Flare to author in, but the DITA output is simply way too basic and not 100% DITA compliant (I've logged the bugs), which means I simply can't exchange information with other writers using strict DITA compliant tools. So, yes I would love to see Flare support more DITA compliant things.

Wayne

[RamonS]

Yes, that is one of the cases where DITA is a big help. DITA is for tech writers what is HTML for most browsers or ODF for documets. Besides that, the file format is of not much use unless some toolkit is out there that can transform the stuff into some esoteric format that not many use.
Since the DITA OT does support some more interesting formats I put in an enhancement request to make Flare have a GUI front-end for the DITA OT. That should help those folks who ask for Java or Eclipse help and the amount of development on MadCap's part is smaller than implementing native support..

[forfear]

Ramon, my only comment on your thoughts is that recently we have found the ideal situation where DITA is going to be helpful. That is, we sold off one part of our company. The other company who bought it isn't using any of the same tools we did. However, they are using DITA and we're finding that the transition of the data from one system to another is turning out to be much easier than anybody (myself included) thought it would be. I'm also not sure I agree with your assessment that DITA is a fad. However, I'm not sure it's growth rate is going to skyrocket. It will simply be one of the many structured environments people can work in. Although, if you follow any of the STC articles and papers, you would think that if you're not using DITA you're way behind the times, and I suspect that may be where some of the ideas of it being over-hyped come from.

But, you're right. At times I feel very handcuffed dealing with the restrictions of DITA, which is why I agree with you that as a concept it is exactly what people need to be doing. Thinking of things as chunks of information. However, one of my pet peeves about the DITA community as a whole is they have adopted that message to the extreme. The DITA spec certainly looks better now (v1.2) than it did in previous versions, but it certainly isn't a shining example of DITA output that you could take to a group of people and sell the idea of going into DITA with. The community at times has lost the fact that information layout is as important as the information itself at times. Wall-to-wall text on a page while technically accurate isn't the ideal way to learn. And certainly dealing with the Open Toolkit, XSL-FO and the various things you have to do to render DITA outside of tools like Flare make it much harder to implement an output that presents information in a way that makes learning the information easy.

That said, there are times that I would love to use Flare to author in, but the DITA output is simply way too basic and not 100% DITA compliant (I've logged the bugs), which means I simply can't exchange information with other writers using strict DITA compliant tools. So, yes I would love to see Flare support more DITA compliant things.

Wayne

How apt!

[forfear]

I would certainly like to add myself to the group of Flare authors who would like to see more compliant DITA output support.

It would be really interesting to see how the MadCap team and for that matter, how the MadCap XML authoring interface can be used to simplify the DITA markup authoring process.
There is a lot of potential for the MadCap XML authoring interface to be applied successfully as an elegant authoring solution in contrast to other slightly more cluttered dita/XML authoring interfaces. Cluttered authoring interfaces where content and markup share the same edting space on a screen, tend to promote an error-prone, slower authoring environment where authors have to visually filter between markup and content - a signal vs noise problem. Sometimes you have to switch between non-markup views so you can literally uncover your content from the mountain of dita markup in the process.

[Gary Taylor]

The last post to this discussion was in 2011. Does anyone have an update or further thoughts about the issues?

[wbrisett]

I have done some converting of content with Flare recently (from MS Word to Flare to DITA). The results weren't stunning, but better than using the copy-and-paste method to get data out of word and into DITA.

Since moving to another company (also using DITA), I'm using Flare less and less. That said, I miss how Flare allows you certain freedoms in structure that you don't have in DITA.

Even with the latest version of Flare, the DITA export isn't wonderful, but you can use it in a pinch.

Wayne

[chunkee]

I have found that Flare is a bit more flexible than DITA. The usage of SNippets as well as tag assignment and the Relationship Table has proven to be quite powerful on my projects. Creating a customize entry for the relationship table can color outside the lines that DITA is constrained by. In the end it is a preference. I am hoping that Madcap will start integrating and using more authoring tool sets with the jquery back end. The UX portion of content strategy is very important. DITA has its place for the structuring of content, but the presentation layer along with find ability, readability and contextual related content is just as important.

john c

[wbrisett]

John, I don't think you're going to get much argument about Flare being more versatile in so many areas. That said, there's a load of customization that can be (and is being) done in DITA. The real problem is you have to have full-time programmers to make all the magic happen. There's a lot of work that needs to be done in the DITA arena as far as presentation, but most of the DITA implementation folks don't go into that part, which is why I think programs like Flare have huge advantages. I'm in another DITA shop right now and they have been at it for three years and are just now starting to produce 100% DITA documentation. Loads of money and effort have been tossed at it... large companies can do this, small to medium size companies not so much so...

Wayne