RE: Narrative Technical Writing

Subject: RE: Narrative Technical Writing
From: "Janoff, Steve" <Steve -dot- Janoff2 -at- Teradata -dot- com>
To: "Chris Despopoulos" <despopoulos_chriss -at- yahoo -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 3 Nov 2009 13:14:12 -0500

Hey Chris,

You know, combining the idea that "procedures are largely obsolete" (who
said that? not me!:) with what you say about social technology, consider

I'm not a big user, but I would bet that most Gen-Y or whatever they're
calling them now people can set up an account and use the thing on a
daily basis without ever having to consult the help or any kind of
manual (which I doubt exists).

I mean, there are aftermarket manuals for Facebook, but who really needs
'em? Probably boomers. (Gritting teeth: Yes, I'm one.:)

That's the future of tech writing, at least as it relates to GUI's --
sure, they sort of *have* to deliver help for the thing, so somebody's
got a job; but really, in the past it might have taken a team of writers
to write the doc for such a web site (think eBay, Google, etc.).

Web applications are becoming so easy to use, the eventual "help" might
be a 1-page cheat sheet.

Btw, someone else mentioned the For Dummies books too, but I'll tell you
something about that series: when it first came out, the books were
fun. Then it became this homogenous wall of same-old-thing
documentation, and they all looked the same. Plus, they have FAR too
many words, and plus, that was fun in the early days when you *wanted*
something narrative like that for GUIs. Nowadays you just want to get
down to business. So I haven't looked at a For Dummies book in years,
even though I collected a bunch of them along the way.

Actually, I came up with things like "Longitude" by Dava Sobel (which I
never read but dipped into a little -- it looked good), the books by
Simon Winchester ("The Professor and the Madman" was a wonderful read,
or listen, since I consumed the audiobook version while commuting back
and forth to work over a couple of weeks), and maybe works by Edward O.
Wilson, the ant guy.

But you're right, science writing seems to be where it's at for this
kind of leisurely, sumptuous writing. Per Robert's note, I had even
gotten a book by M.F.K. Fisher some years ago, and she had an absolutely
wonderful style.

(Interesting, Robert, what you say about the cookbooks. Thanks for that
-- good information.)


-----Original Message-----
From: techwr-l-bounces+steve -dot- janoff2=teradata -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+steve -dot- janoff2=teradata -dot- com -at- lists -dot- techwr-l -dot- com]
On Behalf Of Chris Despopoulos
Sent: Tuesday, November 03, 2009 9:13 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Narrative Technical Writing

Comments inline...

# Hi Chris,
# Yes, I jumped ahead, so apologies for that.
# But here are some random thoughts:
# Minimalism and DITA are based on the task. If we weren't writing #
task-oriented "how-to" content, what would we be doing?
# And by the way, the way I meant what I said ("our role largely makes #
procedures obsolete") is in the spirit of your point that we don't have
# to drill down nearly as far in writing task-oriented material. So
maybe # very brief, high-level task instructions. A simple 1-2-3
without much # detail.

Well... With appropriate detail? And maybe we can move other details
into a different section or at least a different format. We're still
kept busy making choices and clarifying the details. In fact, I'd say
that if we can get away from holding people's hands through the
particulars of each dialog box control, then we have more room to
provide even more value. In other words, we work harder. We have to
understand the product even more, and we have to understand the real
world even more.

# The trend is away from writing conceptual material. And reference #
material is often just thrown together into tables and such.

That's a trend that started in the 80's. Is it still viable? How much
was it driven by cost issues, and justified by research after the fact?
Are we really willing to believe that user interaction hasn't changed
significantly since then?

# The little I've poked around in tech writing history suggests that #
writing was a way to memorialize things that had formerly been handed #
down through oral tradition -- similar to how scribing and then printing
# memorialized the Iliad and Odyssey, the Bible, and other great texts.
# But this time, the focus was scientific and technical information.
# Things became too complex to hand down by a journeyman teaching an #

Another thing about text is that scientific progress (and so
technological progress) wouldn't be possible without it. Not only is it
a memory crutch. It's a unique way to analyze thought, recombine it,
and explore consequences. Look at poetry -- how many poets meant to
write one thing, and because of the limits of their form, found the
words they chose meant so much more than they could have intended?
Poetry is awesome because the goal is often to have meaning explode.
Technical writing is equally cool, except that the goal is to have
meaning implode (to carry the metaphor too far).

# A lot of us document software GUIs. One of the big points you've been
# making is how much detail is needed anymore, regarding how to operate
a # GUI. Very little, really.
# Another thing: Have you ever noticed that one of the easiest ways to
# learn how to use a new tool is to have someone on the team who's #
familiar with it sit down and show you a couple shortcuts? Within #
seconds, you're up and running. Okay, that's not going to get you very
# far with something really complex, but it's great for simple #
productivity tools.
# So the oral tradition continues, in a way.

Absolutely... Technology outside of a social context is a bit like a
tree falling in the woods. Social groups use technology as they see
fit. In the financial world the line between social and technical
constructs gets real blurry... everything is so proprietary. There the
GUI terminology is nearly equal to the real world terminology, and
understanding one comes close to understanding the other. (I

# Years ago somebody told me that John McPhee had been a technical
writer # (I can't find any support for that on the web, though). I only
read a # little of his nonfiction but it seemed really nice. I guess I
sort of # yearn for the days -- if they ever existed -- when you could
really take # your time and write something that really moved a reader
at the same # time it educated them. The goal of technical writing in
those days (or # those imaginary days) was to educate and inform, and to
some degree # create an aesthetic experience. But of course, nowadays
that would be # considered way too narrative, not to mention
prohibitively expensive.
# So we're not really writers in the traditional sense.

Well, if technology is the new religion, maybe we're more traditional
than you suspect...

# Okay, so maybe one has to look for a more recreational kind of
technical # writing to read, just for enjoyment. Like Thoreau or
someone like that.
# Meantime, if anyone has come across any such texts like that, that are
# really enjoyable to read and are considered examples of technical #
writing, I think they'd be worth checking out, and would be grateful for
# a reference to them.

I think I've mostly found this in scientific writing. Not really
technical writing, I guess. I'm actually reading Darwin's "The Origin
of Species" (it's about time), and finding it quite enjoyable. It's
nice to read how the thought develops. But I think we're not supposed
to go there in our work. Nothing but the fax, mam. But I'll try to
keep my eyes open. Maybe the "For Dummies" series qualifies in a way.
Not that it's an enjoyable narrative, but they use lots of devices to
bring a certain reader in.

# TIA, and as for this thread, maybe I'm just yearning for something #
that's not commercially feasible in today's world, and as I say, may #
never have been.
# PS - Of course, this kind of narrative writing for leisurely #
reading/learning is the *opposite* of minimalism! I mean, some of us #
write these long posts -- are we not frustrated narrative writers? :) #
# PPS - By the way, just to kick this off, I don't cook, but I'll bet #
there are some wonderful old-timey cookbooks that get into this sort of
# leisurely technical exposition of how to create wonderful meals that #
make your mouth water just reading about them.

You might have something there. Sort of a melange of market copy, use
case, and sequence material. You *want* to do this because you'll
achieve your goal with sumptuous results. And the recipe intro often
includes a preview of the sequence, trying to convince you that it's not
as hard as you might think. Oh, and if you have an idea of the
sequence, then you know which measurements are critical and which you
can fudge according to taste. The good old cookbook comes through yet

# -Steve

Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at:

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:


Re: Narrative Technical Writing: From: Chris Despopoulos

Previous by Author: Narrative Technical Writing
Next by Author: RE: Narrative Technical Writing
Previous by Thread: Re: Narrative Technical Writing
Next by Thread: Re: Narrative Technical Writing

What this post helpful? Share it with friends and colleagues:

Sponsored Ads