Skip to main content
Reviews

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.

Sarah O'Keefe
January 17, 2007
Read More
News

Ten for ten: training discounts until January 31

In 2007, we’re celebrating our tenth anniversary at Scriptorium. As part of this milestone, we’re going to offer discounts and giveaways throughout the year.

Our first special is 10 percent off any public training class on FrameMaker, XML, XSL, InDesign, or Photoshop. To get the discount, use the following coupon code during the checkout process in our online store:

10for10training

The code is valid through January 31, so register soon! For class dates, go to our online calendar.

Fine print on the discount: You can use the discount code only one time, so if you want to take multiple classes, register for all of them in one order.

Alan Pringle
January 12, 2007
Read More
Opinion

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.

Sarah O'Keefe
January 11, 2007
Read More
News

Party Time!

Here at Scriptorium, the party is just getting started. 2007 is our tenth anniversary year, and since we’re always looking an excuse to celebrate, we plan to have an anniversary announcement every month. Or perhaps the first ten months.

Or when we get around to it.

Look for our January anniversary announcement later this week.

And if you have any suggestion on celebratory goodies for customers, please let us know in the comments.

Sarah O'Keefe
January 2, 2007
Read More
News

Holiday slowdown…if only!

Most years, we slide into the holidays gracefully. Around Thanksgiving, we are busy, but by mid-December, we’ve delivered our end-of-year projects and are beginning to kick back for the holidays.

Not this year.

I’m not sure exactly what happened, but we have several projects due in January, and there is no slowdown in sight.

(Over the years, I’ve come to count on a slow couple of weeks around the end of the year during which I can finish up some long-term planning. This year, I will apparently be going to Plan B…when I figure out what that is.)

Sarah O'Keefe
December 18, 2006
Read More
Humor

Life, liberty, and the pursuit of maple syrup

Wednesday evening, I detoured from XML 2006 in Boston up to Nashua, New Hampshire, for a presentation at the STC Northern New England chapter.

(Thanks to Char James-Tanny for providing transportation!)

Traditionally, presenters are given a jug of maple syrup. Yum. I love maple syrup.

But sadly, the TSA does not permit maple syrup in quantities greater than three ounces in your carry-on luggage. And I don’t check luggage except under extreme circumstances. (And transporting maple syrup doesn’t — quite — qualify.)

My thoughtful hosts, however, decided to give me maple taffy and maple cream cookies instead. Much appreciated.

Note: Cattle prods and throwing stars are permitted in checked baggage only. Good to know before my next on-site class . (And no, I am not making this up. Look under “tools” and “martial arts & self-defense items”)

Sarah O'Keefe
December 8, 2006
Read More
Conferences

XML 2006: Not the takeaway I was expecting

A conference presentation is a specialized form of technical communication — in addition to basic technical writing skills, a presenter needs the ability communicate effectively in a conference session. The presenters here are technical experts, but many of them are really terrible at the front of a room!

For example, they are making the following mistakes (some presenters are doing all of these):

  • Reading slides
  • Slides with too much text in too small a font (the vast majority of the presentations)
  • Mumbling
  • Poor microphone management (not talking into the microphone, moving back and forth so that the volume goes up and down)
  • Poor time management — spending too much time on introductory material and not enough time on the important bits of the presentation
  • Speaking in extreme monotones
  • Sentences trailing off in volume

I don’t know exactly how conference proposals were evaluated, but it looks very much as though content is king (sounds good, right?) Proposals were evaluated on technical merit and little or no consideration was given to presentation skills.

Unfortunately, this doesn’t work. If you have great knowledge, but are unable to communicate that verbally, then putting you at the front of a room full of people is not helpful.

And worst of all, there are NO EVALUATIONS! That means that there’s little or no chance that the situation will be addressed next year. (There is an overall conference evaluation form, but you have to remember to go get it at the registration desk.)

Joe Welinske of WritersUA does the best of job of speaker assessment I’ve seen:

  • He asks participants to fill out evaluations for each speaker. There are just a few questions, and each evaluation is an entry for a door prize. In other words, he bribes participants to fill out the evaluations.
  • Speakers who suck with poor evaluations aren’t invited back the next year.
  • He rarely allows panels or group presentations (too much diffusion of responsibility).
  • Speakers who were rated highly in the past get stars on their bios, so attendees have some additional information to help them choose a session.
  • Joe attends many conferences each year to evaluate prospective speakers and to gauge which topics are getting the most interest from attendees. He builds his program based on this research.

The contrast between the presentation quality here and at WritersUA is really quite stunning.

Sarah O'Keefe
December 6, 2006
Read More
Conferences

XML 2006: Content Management APIs

How Google and wireless access have changed the world: I’m sitting in this session, and the presenter’s approach isn’t working for me. So, I google jsr 170 and I find this article at CMS Watch that explains it quite nicely.

Having skimmed that, I return my attention to the presenter, and find that he’s making a lot more sense.

The CMS Watch article has an excellent definition of JSR 170:

JSR-170 promises the Java world, and possibly beyond, a unified API that allows accessing any compliant repository in a vendor- or implementation-neutral fashion, leading to the kind of clean separation of concerns that characterizes modern IT architectures. Some people call JSR-170 the “JDBC [Java Database Connectivity] of Content Repositories.”

Now, we have Michael Wechner presenting on what is theoretically the same topic. Only not. He leads with this: “Today, every CMS is producing its own user interface, which is just kind of silly.” And then this analogy: mail servers are standardized, but you’re free to use your own client/front end. Similarly, CMSes need a common backend and you can do whatever on the front end.

I feel smarter already.

Wechner’s company, Wyona, is an integrator for open source CMS.

He points out that the ability to work offline is important because people aren’t always online. He uses the example of a train ride in Europe — the obvious equivalent in the United States is airplanes. (Side note: If people are permitted to yap on their cell phones in-flight, I’m probably going to stop traveling altogether. It’s bad enough on the ground at the gate.)

OK, and I think he’s proposing that you use existing protocols, such as Atom and WebDAV, to do CMS connections.

Sarah O'Keefe
December 6, 2006
Read More