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: "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 20:14:01 -0500

Chris,

Could you be specific about what you mean by the "task-oriented mantra"?
Do you just mean having the task be the starting point of the
documentation, as in minimalism and DITA, and then having everything
else be in support of that?

How do you propose formally reevaluating the task-oriented mantra?
Which modern design methodologies are you talking about?

I think we can all agree that the weighty tomes of yesteryear can be
replaced by far, far shorter cheat sheets of task-oriented material, as
in Robert's earlier example of a 2,000-page manual being boiled down to
130 pages.

But where do you go from there? Are you talking about expanding
conceptual material? It doesn't seem like there are a lot of places to
go.

Are you talking about *not* starting with the task as the foundation for
the doc?

I'd be interested in hearing what you envision as the starting point, or
what you see the different features of such documentation being. It's
hard to picture what you might be thinking of when you talk about
reevaluating a task-oriented approach.

Thanks,

Steve

-----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:32 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,
Issue 27)

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:
http://www.doctohelp.com/

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! http://www.helpandmanual.com/

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

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

Previous by Author: RE: Narrative Technical Writing
Next by Author: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)
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