Skip to main content

Author: Sarah O'Keefe


Why XML and structured authoring is a tough transition

Found on technicalwriter’s blog:

There are several applications that incorporate features for DITA use, such as XMetal and Altova Authentic, but how much value do they provide? (Looking over the online documentation for XMetal, you will see some pretty shaky formatting and copyfitting.)

There may well be formatting and copyfitting issues. Wouldn’t surprise me at all. But talk about missing the forest for the trees!

DITA/XML/structured authoring are important because they improve how information is stored. To question their value because somebody produced documentation using them that doesn’t look so great…let’s try an analogy:

Last week, I went to a restaurant and the food was terrible. I looked in the kitchen and saw Calphalon pots and pans. I conclude that you should not buy Calphalon because the food they produce is terrible.

The quality of your food is determined by things such as the quality of the ingredients and the skill of the chef. The pan you choose does contribute — it helps to use the right size and a high-quality pan, but to dismiss DITA because one example doesn’t look quite right is pretty much like dismissing Calphalon because somebody once cooked something that didn’t taste very good in it.

PS I like Calphalon. And I have produced my share of problematic entrees.
PPS DITA is not right for everybody.

Read More


Look in the dictionary, see a reference to MadCap Software. Their latest:

MadCap Blaze is the heir apparent to Adobe FrameMaker.

I haven’t seen Blaze, and as far as I know, it is not yet available in beta. Therefore, this claim seems just a tiny bit premature.

Also, Blaze is going to have tight integration with XML Paper Specification, otherwise known as “PDF-Killer.”

I blogged about XPS early on, when it was code-named “Metro.” I’m very skeptical about XPS; dislodging PDF will take a huge effort. I’m puzzled by MadCap’s focus on XPS.

Read More

The end of the world is approaching

What other explanation is there for Adobe, nicknamed The Cone of Silence, making this announcement:

If you are planning to attend the [STC] Conference [in Minneapolis], you now have added incentive. We will be providing technology sneak peeks of the features of the next versions of FrameMaker, RoboHelp and Captivate.

For details, see Vivek Jain’s blog entry on the Adobe TechComm blog. No mention of a requirement for a non-disclosure agreement, so I assume any information shared at these sessions will be public.

I won’t call Adobe “transparent” just yet, but this reduction in opacity is quite welcome.

Update (May 3, 2007): Over at Core Dump, a post on the same topic entitled Hell is Freezing Over.

Read More

Writing better XSL

Jeni Tennison has a new blog. Her latest post has tips on when to use template matching, named templates, and for-each statements.

In my experience, most people who are new to XSL overuse for-each loops, because they most closely resemble familiar programming constructs.

Read More

It’s not easy being green

Over the years, we’ve been quite smug about Scriptorium’s eco-friendly credentials. We don’t have any nasty, dirty factories, we mostly provide services, and all in all, we’re pretty clean.

On the surface.

It turns out, of course, that there are two major holes in our green company argument:

  • energy
  • air travel

On the energy front, we use power to heat and cool our office and to run our (many) computers. When we travel to visit customers, we usually fly, and airplanes emit huge amounts of pollutants.

In honor of our 10th anniversary, and for Earth Day 2007, we are announcing several new initiates to help reduce our environmental footprint:

  • Recycling: We already recycle most of what we use in the office: paper, computers, aluminum, and plastic. We are also going to make a significant effort to use more recycled paper when we print, both in the office and with our print vendors.
  • Air travel: Through, we are purchasing carbon offsets to “zero out” the carbon emissions from our collective air travel. We are also offering our customers the option of live, instructor-led web-based classes, which eliminates travel requirements for client and customer alike.
  • Energy: We have joined the North Carolina GreenPower program, which allows us to purchase energy from renewable sources.

You can find a list of carbon offsetting programs in several countries here. There’s an excellent overview of the concept at and

Read More

Friends in new places

We’re pleased to announce that we have joined XMetaL’s Partner Program as a Certified Service Provider.

We will not be reselling XMetaL software, but we will begin offering XMetaL classes this summer.

This is really a customer-driven decision — we have clients asking us to develop XML and DITA implementations with XMetaL as the core authoring tool.

Read More

WritersUA: My sessions

I delivered a session on Coping with the XML Paradigm Shift, in which I introduced my Taxonomy of Problem Writers for the first time. The slides are available in PDF format, and I welcome any and all comments. You probably won’t be surprised that the presentation is slightly over the top. It has, however, already served as a great conversation starter —
I heard people talking about Technosaurs and One-Trick Ponies.

On Tuesday afternoon, I did a double-length, hands-on Introduction to DITA session. (Many thanks to XMetaL for providing attendees with evaluation copies to use during the session.)

I arrived in the room about half an hour before the session and found a few people already moved in. (Always a good sign.) Trying to install and configure software just minutes before a session like this is a truly terrifying undertaking. And as we got closer to the session time, more
and more (and MORE) people kept coming. By my count, we had at least 35 people with laptops and five more without. (That’s about triple the number I’d normally allow in a hands-on training session.)

There were a few kinks, but we managed to get everyone up and running*, and I think the session was valuable. At the end, I polled the room on whether they were more or less likely to implement DITA and got an even split. Perfect!

We will be extending this three-hour session into a two-day Introduction to DITA class, which we expect to begin offering in mid-summer. Watch this space for more details.

* One person had a Mac, which I hadn’t anticipated. Sorry! The two people running Vista also had some issues. There were a few installation errors, but their software seemed to run OK.

Read More

WritersUA: Pundit panel

The opening session with the ever-popular pundit panel was interesting. Bernard Ashwanden of Bright Path stole the show with a strip routine. Perhaps I should explain.

Bernard pointed out that life was about content, and the tools were just layers on top of the content. To illustrate the point, he took off his vendor shirt, revealing another vendor’s shirt. Then, he took off the second shirt to reveal yet another vendor’s shirt. After five shirts, he ended up with a MadCap T-shirt. I’m going to assume that this was related to shirt size and not some sort of message about who is closest to his heart. I should stress that Bernard did keep his last shirt on.

Although predictions were created independently by the various pundits, they were in substantive agreement in many cases. Everyone felt that the cliched web 2.0 will have a significant effect on technical writers. In a world where end users contribute to product information on wikis, user forums, podcasts, or videos, what is the role of the “corporate” technical writer?

Several people predicted a demise for traditional help authoring tools. They said that tools must evolve to support new media and community publishing models. I agree in part, but I don’t think this will happen in the next three years, as at least one panelist predicted.

As consultants, it’s our job to understand new technology and to be ready to implement it for our customers. But our customers are at different points on the technology adoption curve. We have:

  • Early adopters, who want the latest and greatest technology.
  • Cautious middle adopters, who want to implement proven technology.
  • Late adopters, who are the last ones to move into a new workflow.

As a result, at any given point, our active customers are:

  • Implementing the latest thing
  • Implementing the low-risk thing (which was likely the Next Big Thing five years ago)
  • Implementing the industry standard (which is robust, but not very cutting edge)

The web 2.0 technologies are still on the extreme bleeding edge. A few companies are implementing them (the Quadralay wiki comes to mind), but corporate adoption is going to take years. Furthermore, user-generated content presents enormous logistical, legal, and corporate positioning challenges, which will slow adoption for risk-averse companies (which is most of them).

Read More

WritersUA: Overview

Attendance seemed to be up a little from last year with approximately 450 people at the show.

Great energy as usual, people were excited to be at the venue.

I got a chance to catch up with many of the Usual Suspects including Char James-Tanny, Alan Houser, Neil Perlin, Paul O’Rear, Dave Gash, Brian Walker, Tony Self, and many others. (If I left you out, it’s because my brain has turned to mush.)

Our booth was extremely busy, and we had great conversations with many attendees. In past years, we would tell people what we do (“XML blah blah structured authoring blah blah FrameMaker blah blah training consulting blah blah”), and some percentage would respond with, “Oh, I use [some help authoring tool] and I don’t need that stuff.” This year, there were two types of responses:

  • “We’re working on an XML implementation.”
  • “We’re thinking about XML.”

The percentage of attendees who do not need to care about XML was extremely low.

Our “Yellow Thingies” were very popular — in addition to chocolate (of course), we were giving away a printed, bound version of three of our white papers (with a yellow cover). You can get the white papers through our online store (free with registration), but attendees really seemed to appreciate the printed version.

Read More