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

["Janoff, Steve" <Steve -dot- Janoff2 -at- Teradata -dot- com>]

Forwarded at the request of Chris...

________________________________

From: Chris Despopoulos [mailto:despopoulos_chriss -at- yahoo -dot- com] 
Sent: Friday, November 06, 2009 8:39 AM
To: Janoff, Steve
Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,
Issue 27)


Hi Steve...

I have to be kind of brief (audible sigh of relief all around).  

Modern design is centered on characterizing the user and developing use
cases. UML captures the approach pretty well:
* Use cases
* Sequences
* Module interactions
* Class diagrams

I know I've glossed over tons here, but this is what I've seen done in
real-world use of UML. Actually, I see darned few diagrams of modules
interacting -- that level of design tends to be hand-wavy and people who
make more money than I'm comfortable around do that stuff...  They tend
to reinvent diagramming vocabularies for the situation.  The point is,
writers belong in the use case and sequence meetings.  Especially in
Agile environments, they're encouraged to be there.  So long as you
really think and participate it's worth the time, believe me. (If you're
documenting an API, get thee to the class diagramming sessions.)

Beyond that, I think I need to produce an example.  Any ideas of some
open source product that needs documenting?  Maybe I should just shut up
and put my money where my mouth is.  

I want to state again, very clearly...  I am not saying we should ditch
task orientation.  I'm saying we should reconsider how we define a task.
I have no idea what the impacts on DITA or minimalism would be.
Certainly, that should be secondary -- we don't want to get into
designing information delivery around the technologies and standards of
the day.  

I'm impressed with one problem we all face...  Until technology provides
an inexpensive alternative we're stuck producing as few different
manuals as possible for a product.  That means we have to shoe-horn a
range of information services into a single type of document.  All the
more reason to be feeling restless, IMO...

Cheers          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: Thu, November 5, 2009 9:15:56 PM
Subject: Re: Doc Design and Convention ( was TECHWR-L Digest, Vol 48,
Issue 27)

Hi Chris,

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.


cud
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 and Manual 5: The all-in-one help authoring tool. Full support for 
team authoring with multi-user editing - both directly and in combination
with VSS-compatible source control systems. 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