Skip to main content

Author: Sarah O'Keefe



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

VC pitch template

This week, I attended the Southeast Venture conference, held at the new Umstead Hotel in Cary, North Carolina. The conference was only about two miles from our office and the opportunity to see this brand-new, five-star aspiring hotel was too good to pass up. (Hard to justify staying there when home is less than 20 minutes away…)

The conference included a series of 10-minute pitches from various companies looking for funding.

After seeing a couple dozen of these sessions, I have put together a helpful template for anyone looking to do a demo pitch.

First, be sure to use the following phrases:

  • “addressable market is over $X billion”
  • “unique value proposition”
  • “sustainable advantage”
  • “barriers to entry”
  • “strong intellectual property assets”

Then, you’ll need two charts. The first one shows revenue and looks like this:
Revenue from 0 today to $50 million at some future date
The second one shows profits and looks like this:
Profits currently zero, drop to negative, then increase to $50 million at some future date
So. Hockey stick and check mark. It’s all very simple.

Read More

A business built on accessibility

In this month’s issue of Inc. Magazine (which I read religiously), you’ll find a feature article on Anna Bradley, who runs a business called Criterion 508 Solutions. (Unfortunately, the full article isn’t available online until later this month, but you can see the abstract here.)

My interest in the article is personal — one of the Criterion contractors featured in the article is Brian Walker, who I know from his presentations on accessibility at WritersUA. Congratulations, Brian!

Web site accessibility has been in the news recently because of the lawsuit. (Target’s web site has major accessibility problems.) Ms. Bradley points out that making web sites accessible is inexpensive — certainly cheaper than litigation and horrid publicity (i.e. “Target doesn’t care about blind people”) — and furthermore, an accessible web site allows an organization to increase the number of customers that use the site. In other words, from a business standpoint, it’s pretty easy to justify spending money to ensure that more people will be able to buy things from you.

Read More

An example of good technical writing

Not too long ago, I took a quick look at XMLMind XML Editor (XXE). I downloaded and installed the software, dropped in a couple of existing XML files, and tried to create some new content.

I didn’t like it. Couldn’t get it to do what I wanted.

This week, I ran across Antonio DaSilva’s article about XXE (hi, Tony!). I read the article, then opened up my copy of XXE (still installed). And suddenly, the product worked just fine.

XXE isn’t my favorite XML editor, for the price, it’s a great tool. (The standard edition that I’m using is free.)

There were a couple of bits of information in the article that really helped me. I think the key insight that Tony provided for me was that XXE does not permit your content to be invalid. Thus, if you try to paste an element into an invalid location, the paste action is blocked. I don’t like it, but at least now I understand why the software is behaving the way it does.

Many thanks to Tony for a great article.

Read More

If it’s not Scottish, it’s…

[refresh your memory here]

The Aberdeen Group has released a new report, entitled The Next-Generation Product Documentation Report: Getting Past the ‘Throw-It-over-the-Wall’ Approach. (Could that title be any less, um, Scottish?) Access is free until February 23 when you provide your email address.
The Content Wrangler
is not impressed:

The folks at Aberdeen do not truly understand the market, despite many interviews with thought leaders in the documentation arena. […] The survey appeared to be designed to obtain results for each of the sponsors […], instead of questions designed to paint an accurate picture of the documentation industry without regard for the concerns of sponsors.

I lost interest because I think their basic hypothesis is wrong:

Causing a missed product launch because of incomplete product documentation is
the nightmare of every documentation manager.

The vast majority of documentation groups that I’ve worked for/in/with don’t worry about “causing a missed product launch.” If the documentation isn’t ready, the product will still ship. The documentation may be incomplete, inaccurate, unreviewed, or otherwise problematic, but the product will ship.

I know that there are some industries (medical devices come to mind) where documentation is in fact regulated just as the product itself is. But the vast majority of technical writers that I’ve worked with are concerned with triage — how much of the doc can be completed by the (generally ridiculous) deadline?

Am I missing something? Is there a world of documentation managers out there who stress about actual product delays because of documentation?

Read More

My First Blog Ethics Challenge

So today, this is all over the various tech comm lists:

If you’ve got a blog that appeals to technical communication professionals, we’d got a special offer for you. Blog about [deleted] and we’ll send you a free [shameless sponsor] T-shirt courtesy of [shameless sponsor].

[boring details snipped]

Supplies are limited. T-shirts XL only.

XL only?!? In that case, forget it.

Now, if they were offering chocolate

On a completely unrelated note, I’d like to mention that I’ll be presenting at the STC Trans-Alpine Chapter conference on April 18-20. In Switzerland, which as you probably know is famous for watches, banks, and <cough> chocolate.

Read More

Anonymous blogging has its benefits

monkeyPi posts a review of RoboHelp 6.

Warning: May be hazardous to keyboards.

RoboHelp 6 finally arrives, and it’s craptastic at monkeyPi

I haven’t looked at RoboHelp in years, so I have no idea whether his issues are valid or not.

[I have this feeling that I know the monkey behind monkeyPi, but I’m not totally sure. Meanwhile, I will continue my demure, unanonymous blogging here.]

I did notice a couple of things about the RoboHelp release. First, based on the feature set, Adobe has clearly decided that XML is not a priority for RoboHelp users. This is in contrast to MadCap Flare, which touts their tool as being “XML-based” at every opportunity. Second, the press release announcing RoboHelp 6 has a quote from the former eHelp VP of Engineering, who is now with an unrelated company (Unwired Software). A lot of MadCap’s marketing effort is built around their identity:

“MadCap Software is just a new name for a group of familiar faces that have been leading the technical writing community for over a decade. MadCap is home to some of the most experienced software architects and product experts in the industry, including many former core members of eHelp Corporation, creators of RoboHelp.”

One gets the impression that Adobe has been paying attention to Flare’s marketing, and that Adobe marketing is just a tad ticked off.

Read More

Somebody does NOT like DITA

From Jon Bosak’s closing keynote at XML 2006:

Another ancient subject that seems to be popping up again is the idea of modular document creation. This is one of those concepts that comes through about once a decade, seduces all the writing managers with the prospect of greater efficiency, takes over entire writing departments for a couple of years, and then falls out of favor as people finally realize that document reuse is not a solvable problem in document delivery but rather an intractable problem in document writing — which is, how to retain any sense of logical connection between pieces of information while writing as if your target audience consisted entirely of people afflicted with ADD.

I don’t think I agree completely, but he does have a point.

I could go on at length about this, but instead I’ll simply leave you with the observation that my personal love affair with modular documentation occurred in 1978 and that I haven’t seen a thing since then that would change the conclusions I reached about it almost thirty years ago. This is not to say that I’m trying to discourage the technical writing community whence I came from their enthusiasm for the modular authoring technology du jour, since engagement in such efforts is virtually guaranteed to buy tech writers a few years in which they can act like software engineers and present themselves as engaged in cutting-edge informational technology development rather than plain old technical writing. That strategy has worked great for some of us.

I think perhaps the arguments for and against single-source publishing are a better place to look. There is a school of thought that argues that single sourcing results in inferior deliverables, both in print and online. But the cost savings from single sourcing are so compelling that nobody really argues for hand-crafting printed and online materials separately any more. (Based on my experience, I think that the quality difference between material that is single sourced (well) and material that is hand-crafted (well) is quite small; perhaps around 10 percent. But that last ten percent is extremely expensive.)

With XML/DITA/modular documentation, there is a similar cost argument. Document reuse and especially localization workflows benefit from modular documentation. For localization teams, getting content in topics rather than monolithic books can result in incremental localization and thus the ability to “sim-ship”; to ship the product in the source language and target languages simultaneously. This, in turn, means a global product launch and a shorter wait for revenue from the markets for which localization is required.

Thus, requirement to accelerate product deliverables and save money on localization (because of more efficient reuse) are going to drive implementation of modular documentation. The argument that non-modular documentation is better documentation will become irrelevant.

Read More