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.
1. Conflate: I knew I'd get in trouble with that one. Just wait till I throw in a healthy "Juxtapose".
2. Modern design docs specifically separate levels of detail. More specifically, they separate implementation from design. They do this because it helps us design and implement the product. We get a benefit -- how is it possible that we have arrived at this beneficial methodology, but it can be of no benefit to the end user?
3. Show me any software or hardware task where knowledge of the use
case or sequence is not useful. Let's really look at this. I believe I've already shown
hypothetical situations where that information *is* useful -- let me know
if I need to be more specific or concrete.
4. Anybody who drives in Manhattan knows that traffic-light synchronization is a useful tidbit. Even rank beginners can benefit from that information.
________________________________
From: Sharon Burton <sharon -at- anthrobytes -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 12:10:44 PM
Subject: RE: Doc Design and Convention
I think you're conflating something. I think you're confusing tell the users
about infrastructure with telling them useful information. For example:
The going-to-a-party use case: I want to arrive at the party. (notice this
is a goal, which generally good use cases are stated as)
* Expert (I know the town and the person throwing the party): The
information I'm told: The party is at Becky's house. I drive to her house. I
don't need more info and will resent anyone in the car directing me.
* Intermediate: (I know the town but not the location of the party) The
information I'm told: The party is at Becky's house. I need cross streets or
general area to drive towards and then turn by turn to find the house.
* Beginner: (I don't know the town and may or may not know the location of
the party) The information I'm told: The party is at Becky's house. I need
to be told every turn and be guided to find the house.
Once you know your audience, you adjust the level of info accordingly. If
you aren't sure of your audience, you layer the information for each level.
At no level do we need to know how traffic signals are synchronized.
But design documents for creating the product may very well do the
equivelent of explaining how the traffic signals are synchronized. Because
that's the infrastructure around which the users are doing what they need to
do. But the users don't care about that - they have a goal and want to
achieve that goal.
sharon
Sharon Burton
MadCap Software Product Consultant
Managing your content, one topic at a time
www.anthrobytes.com
951-369-8590
IM: sharonvburton -at- yahoo -dot- com
Twitter: sharonburton
-----Original Message-----
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: 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 sharon -at- anthrobytes -dot- com -dot-
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-
