Opinion

chutzpah

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.

I didn’t realize I was a lemming

Over at The Content Wrangler, you’ll find a critique of Larry Kollar’s XML Heresy article. I provided some feedback to the critique article, but it occurs to me that if Mr. Kollar describes himself as an XML heretic, then that makes me…an XML lemming?

Excuse me, I see a lovely cliff ahead.

“Perception is reality”

Once upon a time, a long time ago, a wise manager told me this in response to some whining from me. Things were happening, life was unfair, and I couldn’t understand why my wonderful contributions weren’t being appreciated.

“Perception is reality.”

The perception was wrong, and reality was irrelevant. Never mind whether I was doing a fantastic job — upper management didn’t see it that way, and their evaluations are based on their perception.

It seems that RoboHelp has a similar problem. Ellis Pratt writes on the Cherryleaf Technical Authors’ Blog: “The challenge for Adobe, I believe, is to develop a better product and to try and rebuild relationships that haven’t been nurtured properly for the past four or five years. Maybe it’s time they read ‘The Tipping Point’.”

A less emotional take on RoboHelp

Rob Houser of User Assistance Group, Inc. has a review of RoboHelp 6 available at WritersUA.

The food fight over RoboHelp at monkeypi.net and elsewhere has been fun, but if you want a detailed overview of the new features with minimal snark, take a look at Rob’s article.

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.

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?

<crickets>

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.]

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?

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.

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?

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.

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.

Play nicely, and share your code

[updated to fix broken link]

Quadralay’s new ePublisher Pro was released with, shall we say, minimal documentation. The user guide describes how to manipulate the basic interface, but details on how to go under the covers and customize the XSL transformations that make up the core of the product are absent.

It appears that the company is trying to address this shortcoming with a wiki. There are some concerns about this approach, though. Char James-Tanny points out that “no one seems to have the rights to any of the material that’s posted.” And Bill Swallow writes this in waxing techcomm: “If the intent is to supply users with a means of online support/reference, I think it would be best to triage the contributed content, have it validated by a company representative, and then published.”

I think the wiki approach raises a larger question–how much documentation should a product creator be responsible for? A product like ePublisher Pro provides a configuration platform–the customization possibilities are endless. For advanced customization, ePublisher Pro is more comparable to a software development environment than a menu-driven application. Documenting a “development platform” is very, very tricky.

Nonetheless, there are some things that Quadralay should have provided and hasn’t. These include:

• An inventory of the XSL transformation files provided with the product and an overview of what each file does.
• Examples of how to perform common customizations that cannot be accomplished inside the user interface.
• Documentation of the Quadralay-provided XSLT extension functions.

Posting these inside the wiki would be a nice start.

Quadralay has tried before to put the expert user community to work (anyone remember the WebWorks Publisher forums on their web site?). But speaking as a consultant, I’m not likely to post into the wiki when the ownership of that code is so unclear. Furthermore, we already have the wwp-users mailing list, which has over 3,000 members. Why bother with the wiki?

Finally, there is a massive disclaimer as part of the wiki:

All projects, code snippets, suggestions presented in this medium are colloborative [sic] materials expressed by both Quadralay personnel and WebWorks power users. Material taken from this medium and implemented into your existing production workflow or testing environments should be carefully considered and is done at your own risk. Although our product support consultants can and will place material on this medium to faciliate collaboration between Quadralay and its customers, Support Incidents submitted through webworks.com regarding issues with implementation of this material will not be accepted. Support for the implementations expressed here will only be supported through this medium.

In other words, if you use information posted on the wiki by Quadralay to customize your project, and it doesn’t work, Quadralay support will not help you.

Boo.

I understand the concerns surrounding wikis and the ability of anyone to edit a page, but it seems this could actually be resolved quite easily. The wiki can be set up with Official and Unofficial pages. Official pages are built by Quadralay employees, are editable only by Quadralay employees, and Quadralay support will provide support for those pages. Unofficial pages are those created by ePublisher Pro users; they are the “use at your own risk” section of the wiki.

A student reviews a web-based class

In the November 2006 newsletter of the STC UK chapter, Mark Buffery of Salford Translations writes about his experience with the web-based version of our XML and Structured Authoring class.

The course consists of 4 half-day sessions (approximately 2 hours in length each), and is presented as a web-based meeting with all participants in direct communication with one another through a telephone conference call. This enables the tutor to field any questions raised during their presentations, as and when they are raised. Once logged on, each participant can view the tutor’s screen in real-time as they demonstrate and talk them through the various functionalities being discussed. This was the first time I had ever attended a webinar, and I was not sure just how effective this would be.

I firmly believe that, in theory, classroom training is better than web-based training. The trouble is that classroom training is also much more expensive than web-based training. Typically, the cost of travel (at least) doubles the basic tuition expense, and when you take into account the time spent traveling to and from the training site, costs are even higher. Web-based training allows you to fit the training into your regular workday. You do miss out on the many delights of the airport security line, but I think you can probably manage to contain your disappointment.

Being in direct vocal contact over the telephone was useful, and a better compromise than I had imagined (being used to the more traditionally reciprocal teaching environment of the classroom or lecture theatre). However, once we had been online for a few minutes, it did not seem so strange.

If you’re considering this or other courses with Scriptorium, please read his article for an overview of how things work from the student’s point of view.

One common question that Mark does not touch on is class times. Our commitment to our students is that we will make every attempt to schedule the class so that class meetings are during regular business hours for each student. Most often, that results in an 11 a.m. to 1 p.m. meeting at our local time (U.S. East Coast). If we have only East Coast and European students, we move the time earlier; if participants are west of us, we move the time later. So far, we have not had any participants dial in from east Asia or Australia, but please feel free to sign up and we’ll make sure we meet at a time that’s reasonable for you.

Baby Breeze

Adobe announced the availability of Acrobat 8, which now includes Acrobat Connect, the Product Formerly Known as Breeze.

The Product That Formerly Had a Non-Dorky Name is (or was) an online meeting/collaboration/elearning tool. But ex-Breeze (now Connect Professional. Boo) is quite expensive.

With Acrobat 8, though, Adobe is offering a low-end version of Connect, which Claudia McCue promptly dubbed Baby Breeze. For $400 per year, you get an “always-on,” unmetered meeting room for up to 15 people. And a static URL. And a free conference bridge line.

We tried it out last week, and it is very very nice.

I’d like to see the ability to record meetings added to Baby Breeze. Other than that, I’m very impressed.

Right now, Adobe is offering a free trial (and if you convert to a paid account, you keep the URL you establish). If you have any need for web conferencing, take a look.

Source, please?

The DITA hype continues.

The announcement for Arbortext 5.3 is almost completely focused on DITA, and in places reads more like a description of DITA than a press release about a new product. And in the middle, we find this item:

“PTC believes that by the end of 2008, up to 80% of all new XML publishing installations will be based on DITA.” (press release at ptc.com)

Is there research to back this up?

I find it very hard to believe that DITA is appropriate for 80 percent of all XML publishing implementations. Just consider the textbook and magazine publishing industries. Aerospace and pharmaceuticals both have non-DITA standard requirements.

(h/t Gilbane Report News)

Online learning isn’t just for colleges

A recent study found that the number of students in online college classes is still rising:

Roughly one in six students enrolled in higher education – about 3.2 million people – took at least one online course last fall, a sharp increase defying predictions that online learning growth is leveling off.

Cost savings play a big part in the continuing upswing for online learning at the college level, and that is true of our online classes, too. Neither the students nor the instructor need to book flights, rental cars, and hotel rooms, and those costs can be considerable. The financial incentives go a bit deeper than that, though. Each day of our online classes is about 4 hours (2 hours of interactive instruction and 2 hours of “homework” for the students), so students still have time to handle other job responsibilities. It also means our instructors have time to do other work here at our office. (And let’s not forget the wear-and-tear associated with travel today: spending a lot of time on airplanes packed like sardine cans is no one’s idea of fun.)

Overall, we’ve been pleased with our first year of online teaching. Even though having an instructor with you in the same room is probably the best way to learn software and technology, the cost of classroom training eliminates it as an option for many folks. We recognize that, and that’s why we decided to offer online classes. Based on our experience so far, we feel they are an excellent compromise between do-it-yourself learning through books and the classroom experience.

Adobe’s new digital publishing platform

This morning, my Google news alerts start pinging me with information about Adobe Digital Editions. This new software, available as a beta from Adobe Labs, is something of a cross between Acrobat Reader and the Flash player. It’s a relatively small download (2.5MB), and it provides for display of PDF or eBook content.

I should know better than to get involved in this one…

Kathy Sierra’s Creating Passionate Users blog is one of my favorites. But her latest entry is entitled Why marketing should make the manuals!

Ugh.

Read the whole thing, and then let’s chat. I’ll wait.

That’s one mystery of the universe explained

FrameMaker users are a loyal, occasionally even fanatical, bunch. The mystery has always been exactly why that is so. After all, there are lots of software tools out there, and many of them are prettier, faster, and cheaper than FrameMaker. But you don’t hear a lot of discussion about the joys of Visio.

Web 2.0. The inaccessible web?

At O’Reilly.net, Hari K. Gottipati writes that “the main disadvantage of Ajax is [because] a Web page is not required to reload to change, many screen readers or other assistive technologies used by sight-impaired or otherwise disabled users may not be aware of the dynamic changes.” (AJAX Accessibility Issue caught vendors attention. Is this a major issue?)

This is bad.

Freelancing out of necessity?

I’m not sure I agree with all of this article, but it’s a fascinating perspective on outsourcing, freelancing, and virtual corporations.

A picture may be worth a thousand words, but it’s not worth a lawsuit.

We sometimes use stock images for marketing materials, book covers, and the like. We recently found a stock photo site that sells some high-quality images for a fraction of what of you pay at better-known stock photo firms. Buying a royalty-free image for $3 instead of $300 seems like a really good deal…until you read the fine print.

R-E-S-P-E-C-T

In his blog, words / myth / amper & virgule, Dick Margulis focuses mostly on writing and editing. But in today’s entry, he discusses relationships between consultant and client, and I think he summed it up most excellently:

“If you are the sort of person who yells humiliating insults at servers in restaurants, I really would rather not work with you. “

words / myth / ampers & virgule: Growing up is hard to do