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.