RE: TECHWR-L Digest, Vol 48, Issue 25

Subject: RE: TECHWR-L Digest, Vol 48, Issue 25
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: Thu, 29 Oct 2009 21:44:44 -0400

Hey Chris,

Another provocative post -- keep 'em rolling! These are really fun.

A few points, just random thoughts:

* The writer in question (yours truly) wasn't really "floundering," or
at least not unreasonably. Project was to document a product that had
an acknowledged multi-year learning curve. Delayed understanding was
unavoidable.

* DITA and good Information Architecture actually accomplishes what you
suggest about dialog boxes. High-level task topic gives the barebones
basics, no description of fields or values; then a separate reference
topic lists these in a table. But I like what you're saying about
taking task orientation to a higher level. It rocks!

* I know your point was that it's better for the writer to do the doc
*after* the unifying "Aha!" experience than before. But there's no
guarantee that the writer's crystal clear vision will be apprehended by
the user, even with the clearest and simplest of treatments. To
overdramatize, the Zen master cannot "transmit" satori to the student.
Unfortunately, insight has to be earned.

* Idea of getting the writer into the process at the very beginning or
at least very early is ideal. That works great in start-ups and smaller
companies, but pretty tough in the complex behemoths. I don't work at
IBM or Sun, but I can just imagine jumping onto one of their projects
and I would bet that most writers there would share your dream but don't
often get to do it. Great in principle, admittedly rare in practice.

* What you say about use cases is very interesting and stimulates other
thoughts. Maybe for another post.

* True that things are very different since the advent of the
task-orientation mantra. It makes you wonder what we really need to
document anymore, but I believe you've answered that with the idea of
use cases and conceptual information. But one question: Don't use
cases suggest tasks? If I want to assemble a bicycle, aren't you going
to give me a step-by-step procedure on like a foldable sheet?

* Some of the things you've said suggest stepping back from the doc and
abstracting out to what it is we're really trying to do with these
things. What's software for, what are the machines for, what does all
this stuff do that we couldn't do before it was invented? Automation,
taking over menial or repetitive tasks, doing things that use low-level
human skills. Actually, some of it is quite complex so you can't really
say that. Computers do things that would have taken many years without
them and in some cases could never have been done. So in some ways the
machines and software replace the activities of the mind. ... We're
losing touch with the tactile world. Some people still write longhand
just for the sensation. Computer use replaces social interaction but
then you have social media and networking that wasn't possible before.
But you're still not really talking to somebody face to face, seeing
them, hearing them, experiencing their presence. Ultimately you wonder
what's going to be left for us to do.

But for right now, tech writing's not a bad profession. :)

Steve

PS - I forget where I read it but Donald Norman once suggested that the
user manual be written before the product was even designed. That's
almost like screenwriting. A heck of an idea! On the other hand,
you're limited to the writer's vision of how something should be used,
which could be constrained by what he/she is already familiar with in
the world. I mean, could a writer have written the iPod user manual
before the thing was developed? I doubt it, unless that writer was
incredibly visionary.


-----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: Thursday, October 29, 2009 11:18 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: TECHWR-L Digest, Vol 48, Issue 25

Comments in line...

#Chris Despopoulos wrote:
#>
#> If you have the
#> benefit of all this information, then why shouldn't you share that #>
benefit with your customers? Isn't it necessary for you to know all #>
this stuff (whether through formal channels or a self-inflicted A-Ha!
#> moment) before you can fully understand the product? Why should your
#> audience be any different?
#>
#
#Because your audience isn't trying to document the #product and most
audiences don't care how it works #or why it works the way it does. Most
studies show #that for end-user products, most people don't even #look
at the documentation at first, they just try to #start using the product
until they get stuck. When they #do get stuck, they try to find out how
to get unstuck #from the online help or documentation. The user wants
#to use the product, not necessarily to understand it.
#

Is this due to the nature of the user, or the nature of the
documentation? (I know... that's a mean question, but I can't help
myself...)

#Products that are used by people to produce other #products (for
example, programming languages that #software developers use to write
applications) #need to be thoroughly documented because the user #has to
understand the underlying product in order #to understand how to use it.
But most commercial #products do not fall under this category.
#

I was specifically answering a writer who said he had trouble
understanding the product until enough exposure to it gave him an A-Ha!
experience. The type of information we were discussing is absolutely
important for the customer under any and all circumstances... What's
the use case for feature X? Can you name a situation where that's too
much information for the user? The only question is whether you can
assume the use case is known, or do you have to state it explicitly?
But without knowledge of the use case, the user will flounder, period.
Indeed, the writer was floundering as well until he could assemble the
use case on his own.

I'm not saying that users need to know how the underlying data structure
limits the GUI and forces them into convoluted work flows. In fact, the
whole point of designing software from use cases is to avoid precisely
that type of convolution. So I stand by the statement... The writer
benefits from use case information, and why not share that benefit with
the user?
#>
#> My point is that good coverage doesn't come for #> free just because
the docs are "task oriented".
#> And I also maintain that things have changed #> considerably since
the task-oriented mantra was #> taken up.
#>
#
#In what way? Online delivery of documentation means #that we don't have
to worry as much about page count #any more but I don't think it means
that end users #are any more interested in the inner workings of the
#product than they were before.
#

What's changed? Overall computer literacy. I maintain that we still
have conventions geared to a 1980's standard of computer literacy. If
you feel compelled to describe how to use a text box or a check box, who
are you writing to? Even my mother in law would skim past that.

The concept of "end-user product" is at a threshold. It won't be long
before the majority of end-user products are web clients into cloudy
services. Nobody will want to read about how to use the controls on a
web page. What they'll want to know is what the controls actually *do*
and what the service does. The vast majority of (if not all) hardware
config happens through served pages. People setting up edge servers for
a cable service provider definitely don't want to read "Click in the
check box to put a check in it" (actual quote). The check box is
labeled "Split multicast stream". They want to know how the system
splits out a multiplex broadcat (to which codecs, which streams, which
ports, etc.), and how to specify/inspect which multicast channel the
device is getting. If they come in with a solid sense of the use case,
they're a step ahead. From this lower level, if you can describe how
the current action relates to the use case (and maybe others), then
you're documenting the product. But if you describe how to use a GUI
widget, you're just documenting standard GUI concepts.

#-- Janice
#




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Are you looking for one documentation tool that does it all?&#160;
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 Steve -dot- Janoff2 -at- teradata -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/steve.janoff2%40terad
ata.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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Are you looking for one documentation tool that does it all?&#160; 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: TECHWR-L Digest, Vol 48, Issue 25: From: Chris Despopoulos

Previous by Author: RE: Click X, or click the X button?
Next by Author: RE: Doc Design and Conventions
Previous by Thread: Re: TECHWR-L Digest, Vol 48, Issue 25
Next by Thread: Re: TECHWR-L Digest, Vol 48, Issue 25


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


Sponsored Ads