TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
I do get some beginning sense of what you're saying, although it's
sketchy.
I still want to know what the latest ideas in design methodologies are,
or at least give me one hint. :)
My reaction is that it sounds like you're saying that DITA, minimalism,
and the task-oriented mantra have forced us into a one-size-fits-all
approach, or standard (well, I guess that's what a standard is), where,
regardless of the product or its use, you begin with the task and write
everything to support that.
Let's take away the variable that you and Robert(?) complain about,
which is overly detailed task orientation. Assume a manual, or online
help, that has exactly the right granularity of detail for its tasks.
But if it's in DITA and written from a minimalist perspective, then it
no doubt is going to fall into the cookie-cutter mode of the standard.
It will probably look like many other such documents.
What you're suggesting might look a bit different, and might have more
of a mix of types of content -- concept material supplemented by task
content and vice versa, and reference. But it might not follow exactly
the sequence of what you'd see with DITA.
I don't know much about use cases, and took a very brief look at the
Bittner and Spence book, per Robert's reference (as much as you could
see on Amazon, which is actually a lot -- I think up to like p. 86), and
I have to say it looks very interesting. I'm guessing a use-case
approach would produce a very different document than a strict DITA
approach.
I'm reminded of the difference between reading a book to learn something
and alternating between a video demo, an audio treatment, a physical
book, an ebook, pages from a web site, maybe an article somewhere, a
PPT, a "screencast," etc. For example, in looking up "use cases" on the
web, you can bounce from Wikipedia to Amazon to Google Books to an
academic web site to a research paper to a diagram and on and on. And
as I think it was Gene suggested on another thread, if you can't find
info on how to use a software app in the manual or the help, you can
always look it up on the web and hopefully get an answer, which does
seem to happen often.
Maybe there's no way to map the prototypical user. One person's search
path for a piece of information could be very different from another's,
and less by chance than by something else. I'm thinking of level of
sophistication about a product, or prior knowledge, or technical
background. A developer's search path would likely be different from a
writer's, for certain things.
Then there's attention span. Isn't a lot of contemporary documentation
designed for short attention spans? :) Maybe not. But nobody has time
to read the big old doorstop books anymore, even assuming they were
fountains of legitimate info. I mean, Encyclopaedia Britannica would be
a wonderful read, if you had time to get through it. Same thing with
the full OED. Or the Great Books series. Or the Greatest Software User
Manuals of All Time series (if there was such a thing -- that would be a
kick, wouldn't it?).
In short, what you're describing sounds very different from what is
typically done today. I like what I'm hearing. I'd enjoy hearing more
thoughts on this, if you have the time and the inclination.
In fact, what you're describing sounds more like what good software
manuals USED TO be like, just much better organized. I could see a
really good conceptual introducton followed by a task, and stepping
through the document either in different use cases or from the highest
level purpose to lower-level ones.
That Bittner and Spence book looks really good. Just wish I had the
time to read something like that.
Okay, Chris, more thoughts on your use case-based User Guide would be
great! :)
Thanks again,
Steve
PS - Enjoyed the hippie cookbook waffle recipe. Whether useful or not,
that's my idea of fun reading! (And Brian was right about the VW book
-- I remember that thing when it came out. Long time ago!)
________________________________
From: Chris Despopoulos [mailto:despopoulos_chriss -at- yahoo -dot- com]
Sent: Tuesday, November 03, 2009 6:23 PM
To: Janoff, Steve; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,
Issue 27)
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.
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-
