Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)

Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 3 Nov 2009 09:48:40 -0800

The useless docs I inherited were the opposite of task-oriented. The
content showed no awareness by the authors that the software would
ever be used for any purpose. These posers would just sit down, walk
through the software, and write up what they saw, starting from the
File menu and working over to the Help menu, with lots of screen
shots. If you were puzzled by something and pressed F1, you'd get a
picture of what you were looking at with a bunch of text telling you
what you could figure out for yourself.

How do you get from there to "the task-oriented mantra has been abused"?

During the dot-com boom, I met English teachers and writers and
editors from lifestyle magazines and mainstream publishing houses who
switched to tech writing because they could make twice as much money.
The problem wasn't that they couldn't write; it was that some of them
lacked the necessary technical background, and didn't pick it up on
the job.

On Tue, Nov 3, 2009 at 9:32 AM, Chris Despopoulos
<despopoulos_chriss -at- yahoo -dot- com> wrote:
> This is exactly what I'm talking about.  I'm not saying it's the design of the product that's at fault.  I'm saying that the task-oriented mantra has been abused.  I'm not convinced that it's because non-writers have jobs.  Haven't you seen examples of that stuff from people who made it through tech writing courses?  Somehow they were *taught* to do that.
> I'm also saying it's a result of old-think in modern times.  There was a time when you had to explain how a mouse works.  This thread started with the question, how much detail to use when describing a click?  So we're still worried about whether people can figure out a statement like, "Click OK"?!?!  Not really, but we're worried that we need to pay homage to that concern in our style guides.  Bah!
> If we have to formally work through this type of issue, why not go all the way and formally reevaluate the task-oriented mantra?  Why not look at modern design methodologies and map them to new documentation designs?
> (PS -- sorry about screwing up the subject line so often...)
> # More to the point, I've thrown out and rewritten from scratch lots of
> # docs that were nothing but a narrative, illustrated walkthrough of the
> # UI. They didn't tell anyone anything beyond what they could see on
> # screen.
> #
> # The problem was with the writers, not the design of the products. That
> # was partly the result of the dot-com boom, when just about anybody who
> # wanted to be a tech writer could find a job, even if they weren't
> # capable of understanding the technology.

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: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27): From: Chris Despopoulos

Previous by Author: Re: Doc Design and Convention
Next by Author: Re: Narrative Technical Writing
Previous by Thread: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
Next by Thread: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)

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

Sponsored Ads