Re: Doc Design and Convention

Subject: Re: Doc Design and Convention
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tue, 3 Nov 2009 08:40:38 -0800 (PST)

You might skim Bittner & Spence's "Use Case Modeling" to get a sense
of commonly accepted terminology.

Right you are... I've conflated sequence diagrams and use cases.
Oops... Even more design-level information to include in
the docs! Now why would users want to know about sequences before they
start clicking buttons? No need to understand that a valid connection to the server is a pre-req? Or that this sequence might depend on settings from another sequence?

We have new design methodologies specifically to orient design to use cases (images of the real world, one hopes), to separate levels of design, and to separate design from implementation. You're not bogged down in a spaghetti of implementation details, higher-level sequence design, use cases, etc. And if you're not bogged down in this stuff, why should you insist that the user is?

Look, the point is there's design-level
information that benefits the writer in his or her effort to understand
the system. I've seen no convincing argument that the same benefit
cannot or should not be shared with the user. All I've seen is an
argument of degree -- that's an aesthetic choice you make with the
company's stake holders. (That's why they call it writing.) Nor do I see an argument that says use case
is not to be shared with the user, or that use case comes after task (or is backward in some other way -- still not sure what you meant there).
At the highest level, the use case *is* the task. Split multiplex.
Check spelling. Connect to server. Add customer. Oh, wait... to be
tasks they have to include gerunds? I don't think so.

You're driving your roommate to a party in town. Do you want him to tell you, turn here, slow down, change lanes, turn there... Or do you want to know where in town you're going, and then get helpful answers to questions like, which is the best turn-off, how much further down this road, is it on the left or the right? Or worse yet, should your roommate say, "To get to the party, press the accelerator pedal half-way, travel forward (avoiding obstacles) for 3/4 of a mile, then reduce your pressure on the accelerator pedal while rotating the steering wheel clockwise..." You still don't know where the party is. Maybe you don't even want to go to that part of town. How much do you trust your roommate, anyway? From what I've heard (polls indicate users don't read documentation), not much.


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:

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!

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

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 for more resources and info.

Please move off-topic discussions to the Chat list, at:


Previous by Author: Re: Doc Design and Convention
Next by Author: Re: Narrative Technical Writing
Previous by Thread: Re: Doc Design and Convention
Next by Thread: RE: Doc Design and Convention

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

Sponsored Ads