Skip to main content

Author: Sarah O'Keefe


Driving Miss DITA

Over on the Adobe Technical Communication blog, Aseem Dokania compares DITA to transportation infrastructure:

In the XML authoring paradigm, the document is split into structure, content and style, which are analogues to Driving Rules (structure), car (content) and road network (style).
DITA is […] based on the premises that the same set of driving rules cannot be applied to all terrains (desert, mountains, city, etc.). Therefore, DITA allows each country to specialize the driving rules for its own unique requirements. In addition, DITA also has recommendations on the content (car) design – i.e. topics.

Great analogy. Perhaps unintentionally, it also provides an excellent entry point to discuss DITA’s limitations. It’s not that hard to customize cars — left-hand or right-hand drive? two doors or four? red or blue? — but what if you really need a bulldozer? Or a tank??

DITA specialization does have its limits. Before you dive into DITA, spend some time assessing whether DITA’s idea of a topic matches your requirements. How much customization/specialization will be required? If DITA is a good fit for your content, you can probably cut the cost of structure implementation. But if you attempt to shoehorn your publication workflow into a structure that Simply Does Not Fit, life could get pretty unpleasant.

For more on this, take a look at our white paper, Assessing DITA as a foundation for XML implementation. It’s free with registration through our online store.

Read More

Oh, this is not a good idea

[Update: According to Aseem, comments are back on and turning them off was unintentional.]

In an earlier post, I linked to a blog posting from the Adobe Product Manager for FrameMaker, who requested product suggestions via meetings and email. But, unsurprisingly, the requests went into the comments. And most of the commenters are asking for a Mac version. And now we have this (from a comment on my post):

It appears the ability to comment on that post has been turned off. If I had been allowed to comment, here is what I would have written.
[another request for Mac support with a detailed recommendation on how to do it]

I suppose that it’s possible that Adobe’s blog system limits each entry to 16 comments?


Probably not.

I don’t think that a flood of “gimme back my Mac” was what Aseem was looking for. (Hi, Aseem!)

Blogs are a two-way conversation. Sometimes, the person you’re talking with changes the subject. And hitting the mute button is really not the best way to deal with that.

[I will now await a flood of comments that will make me eat my words.]

Read More

And now, a word from FrameMaker product management…

Posted today on the Adobe TechComm blog by Aseem Dokania, FrameMaker product manager:

I have noticed discussions on some blogs and mailing lists regarding the future of FrameMaker. Let me assure you, as the Product Manager of FrameMaker, that FrameMaker is here to stay. We would do what it takes to keep FrameMaker at the leading edge of technology.

Aseem also requests feedback, and I know my readers have opinions, so get those comments going, either here or directly on his post.

Read More

Pod people and RoboHelp

The RoboHelp reviews keep coming, and they’re getting ugly. DMN Communications says in their podcast that the new release of RoboHelp shows “almost contempt” for RoboHelp users (approximately 12:30 into the podcast).

On a more constructive note, the podcasters speculate about the lack of integration of RoboHelp with FrameMaker. They point out that RoboHelp’s competitor, Flare, imports native FrameMaker files, whereas RoboHelp requires use of the intermediate MIF (Maker Interchange Format) files. One of the speakers then muses, “Does Adobe’s agreement with Quadralay [to include WebWorks Publisher Standard Edition in the box with FrameMaker] preclude them from integrating RoboHelp?” (11:40)

I don’t know the answer to this question. Random guesses are so much more fun than the generally mundane truth (whatever that might be).

Read More


There’s no such thing as bad publicity, or so the saying goes.

But RoboHelp is trying.

MonkeyPi weighs in with his, er, unique style. In a lengthy discussion of a recent Adobe webinar on RoboHelp, he says this:

But the kicker comes when [Adobe product evangelist] Jacquez says, “…the closest [online help tool] to RH is Microsoft’s HTML Help Workshop.” The clear implication is that RoboHelp is teh awesome, and teh other toolz are teh suxors. Why even Micro$oft’s crappy free tool places higher then our pathetic competitors!!

Adobe says that their competitors’ claims were misleading:

Jacquez says, “…competitors telling people that [RH] is dead… one has to wonder what the competition is going to say when their customers begin to return their product because they bought it under the pretense that RH was dead.”

Let’s get something very clear here. After Macromedia bought eHelp, they killed RoboHelp. RoboHelp was dead — Macromedia was interested in RoboDemo (now Captivate) and not in any other component of eHelp’s product line. So, they laid off most of the RoboHelp team.

Enter MadCap. Many of the ex-RoboHelp people thought that there was still a market for a help authoring tool, so they formed the new MadCap Software and built Flare. And much of Flare’s marketing was based on the idea that 1) RoboHelp is not going to have any updates and 2) Flare is the natural successor to RoboHelp.

Fine. But then Adobe bought Macromedia. And Adobe does have a significant presence in the technical writing market, so suddenly the strategy changes. Adobe decides to resurrect RoboHelp.

All of this makes perfect sense. And there’s nothing particularly nefarious about what happened. RoboHelp didn’t make sense in Macromedia’s web-heavy product line-up. RoboHelp can make sense for Adobe, especially if they market RoboHelp, Captivate, Acrobat, and FrameMaker as a core set of technical writing tools, along with Photoshop, Illustrator, DreamWeaver, Flash, Acrobat 3D, and others for more specialized requirements. You can see some of this positioning beginning to happening in the Adobe webinar.

Meanwhile, though, response to RoboHelp 6 has been, at best, mixed. One day after MonkeyPi’s dissection of the webinar, we have 10 Reasons Not to Upgrade to RoboHelp 6 at I’d Rather Be Writing. They include the following (read Tom’s blog for an explanation of each item):

1. Communication from Adobe is bleak.
4. Not compatible with Word 2007.
5. Requires at least 15 macros to clean up [print] output
9. Interface is 1996.
10. Its apparent ease of use is only because you’ve been using it for 10 years.

The writer seems particular offended by Adobe’s lack of response to questions and comments during the webinar and on their new TechComm blog:

[…] Adobe’s RoboHelp blogger either is totally clueless about responding to comments, or he doesn’t understand that a blog is not a PR marketing vehicle. […] Sorry Adobe, but you really get a D when it comes to communication.

This is interesting. Five years ago this would have been a non-issue — obviously Adobe gets to control the content of marketing communications on their web site. No more.

As I use RoboHelp about once every five years, I don’t really have an opinion on the merits of the tool. But I am watching the blog-kerfluffle with some interest, especially as I wonder what reaction to FrameMaker will look like, when they release their next version, probably in mid-2007 (according to public statements from RJ Jacquez).

Read More

Authoring styles and art

Norm Walsh tackles topic-oriented authoring and makes a comparison to art.

Imagine that instead of authors, we were painters. In the narrative style, a painter (or perhaps a group of painters) begins at one side of the canvas and paints it from beginning to end (from left-to-right and top-to-bottom). They may not paint it in a strictly linear fashion, but the whole canvas (the narrative whole) is always clearly in view.

Interesting point, and he uses an image of a Vincent Van Gogh painting, chopped into unattractive bits to illustrate what goes wrong in topic-oriented authoring. The flow of the picture is lost.

But what if your content more closely resembles something by Mondrian?

one of Piet Mondrian's cube paintings

Writing useful technical documentation is really, really hard. Using a narrative flow makes it a little easier to ensure that you’ve got the big picture — missing information jumps out at you just as Norm’s chopped-up painting shows.

But topic-based authoring has advantages, too.

Do you need those connections from piece to piece or can individual parts stand on their own?

Are your documents Mondrian or Van Gogh?

I hope for your sake that the product you’re documenting does not resemble Jackson Pollock‘s work.

Read More