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: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "Janoff, Steve" <Steve -dot- Janoff2 -at- Teradata -dot- com>, techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 3 Nov 2009 18:22:47 -0800 (PST)

Hey Steve...

Well, it would be hard for me to be specific about the task-oriented mantra since it's really hyperbole on my part. But I specifically think that well-meaning people have carried a concept to an extreme, and that has unfortunate results. By insisting that docs be task-oriented, we have produced overdeveloped procedures with steps outlining an unnecessary level of detail. It's sort of like over-breeding. Then there are the few miscreants who hide behind this task-oriented idea and provide what Richard rightly called illustrated meanderings through the GUI that don't say anything not already apparent in the GUI itself (my paraphrase - he said it much better). When you criticize, they say it's task-oriented so you have shut up.

To formally reevaluate, I think it might work to follow the latest ideas in design methodologies, and divide what we deliver into categories that indicate how we should write.

I think we *can* be guided by use cases to organize the docs around what people will do with the product. Not only do we expose and/or exercise that design-level organization through our text (and by that reveal design problems that may be lurking), but if we succeed, then the "topology" of the documentation matches the "topology" of the product -- a user who models one models the other. I know there are people who think this is nonsense, but they haven't given me an example where a user does something that doesn't map to a use case. Sure, the designers may have goofy use cases in there... Either we call that out and they make viable use cases, or we make editorial decisions and don't include improper use cases.

Each use case should yield one or more sequence diagrams. I believe sequences can also inform what we do. That's pretty much where the task level goes. A sequence is short-hand for what the user puts into the system, what the system does with it, and what the user gets back. Sequences often show what the system does under the covers, passing data from process to process. So we don't document that part of the sequence. But almost every sequence that has an actor has some input from the actor, and the machine ultimately gives something back to the actor. We document that.

Below sequence diagrams, engineers start designing the implementation. Our analogy is the actual collection of gestures and parameters that people put into the product. I believe we should at least consider *not* documenting this level as procedures, but rather as the collection of gestures and parameters required to perform step X of a sequence. When steps must be performed in a specific order, a GUI splits that into separate dialog boxes or other modal devices to capture input. But each modal device has little or no procedural order within it. So why, for crying out loud, would step 1 be filling in this widget, step 2 filling in that widget, etc.? Instead, why not just list the widgets and describe what's interesting about each? I've already claimed, at this level you can document the GUI in a way that's very similar to documenting functions in an API.

Is this no longer task-oriented? In my opinion it certainly *is* task oriented! But the *level* of the task is different. However, I'm sure there are many people who would say this is not task-oriented documentation. Which brings us full circle, back to wondering about the viability of the task-oriented mantra (whatever that is).

Finally, I've already stated my motivation... Things have changed. On the one hand, people are much more computer-literate. On the other hand, the vocabulary of gestures is getting simpler as products increasingly become clients to the power-house services underneath.

I hope this says it well enough... At some point you have to actually make a doc and see how it works. It's a pity that everybody has to work so hard, and spare time is so hard to find. But you know... it would be cool to see what the results could be.


cud


________________________________
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
Sent: Tue, November 3, 2009 8:14:01 PM
Subject: RE: Doc Design and Convention ( was TECHWR-L Digest, Vol 48, Issue 27)

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

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