Re: Click X, or click the X button?

Subject: Re: Click X, or click the X button?
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Wed, 28 Oct 2009 07:48:41 -0700 (PDT)

A few points... First, you illustrate why it's so important for
writers to be in on the inception of a project. I know how rare that
is, but the only reasonable argument against it is
money (and that's probably a false argument). Otherwise,
everybody agrees that writers can and should contribute from the
earliest point possible. If it happens, then you should be in on the product definition, and how it
fits in the real world... You should already know we're
dispensing coffee and other hot beverages.

modern development is supposed to be based on use cases. That
is, we know a human will put money in a machine to get a cup of
coffee. That's the top-level use case. At a lower level we have cases to
choose coffee properties -- caff/decaf, sugar, milk, etc. Other
beverage types may imply their own special use cases
(chicken/beef/miso, marshmellows, etc.). Before a feature's design
begins, the use case should be clear, and it should be stated in a
context with other use cases. Again, you should be involved at this
point. You're a primary user advocate, after all.

the feature is designed, you should also be involved. Simply put, if a professional writer can't explain how to use a feature, the
design probably needs an intervention.

In other words, you should already know what you need to properly document a product. If you don't, then it's time to tell management how much money they'll save by getting you
into the loop sooner. (Agile is supposed to get you in the loop early. Common practice
thwarts that by putting one writer on many Agile projects.) If you do have the goods, then you need to deal with writing
conventions that make your life difficult.

If you have the
benefit of all this information, then why shouldn't you share that
benefit with your customers? Isn't it necessary for you to know all
this stuff (whether through formal channels or a self-inflicted A-Ha!
moment) before you can fully understand the product? Why should your
audience be any different?

can make some assumptions... A purchase implies the
customer has some sense of the problem space and what the product offers. You have to work with Marketing and Tech Support to zero in on
the right balance. Once that's understood, you have to design your
coverage into the doc set.

My point is that good coverage doesn't come for free just because the docs are "task oriented". And I also maintain that things have changed considerably since the task-oriented mantra was taken up.


From: Marguerite Krupp <mkrupp128 -at- yahoo -dot- com>
To: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>; techwr-l -at- lists -dot- techwr-l -dot- com; SteveJanoff <Steve -dot- Janoff2 -at- Teradata -dot- com>
Sent: Wed, October 28, 2009 9:33:07 AM
Subject: RE: Click X, or click the X button?

Love the coffee-machine analogy!

We might be able to get to the "why" of software if we had access to use cases. Some companies do them, but they seldom filter down to tech writers. Further, some of the companies that do use cases don't do them well, mmore's the pity.

I've been researching Agile documentation, and one of the tenets is that developers (and presumably marketers) sit down early in the process with CUSTOMERS to develop brief "user stories." These are brief use cases--they have to fit on the equivalent of a 3" x 5" card--each of which says what a real-world user wants the software to do...AND...lists the acceptance criteria; that is, how will they know that the software actually does meet the request. And writers do have access to these user stories.

Interesting, eh!

--- On Tue, 10/27/09, Janoff, Steve <Steve -dot- Janoff2 -at- Teradata -dot- com> wrote:

From: Janoff, Steve <Steve -dot- Janoff2 -at- Teradata -dot- com>
Subject: RE: Click X, or click the X button?
To: "Chris Despopoulos" <despopoulos_chriss -at- yahoo -dot- com>, techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tuesday, October 27, 2009, 9:35 PM

Very provocative post, Chris. Been thinking about this off and on all

What you're really talking about is reverse-engineering the engineer's
thought process.

The company starts out with an idea for a software product, with the
product having a goal and a purpose. Then the developer turns that idea
into software.

But the real question, as you suggest, is not how to use the software or
even how to perform a particular task but what is the software for?
What was this stuff originally designed to do? And that will give you a
hint about what the different features do.

So it's very provocative to ask, What is a dialog box? What is its
purpose? As a tech writer I can tell you how it works (old school), and
I can even tell you, step by step, how to perform a particular task with
it (assuming, let's say, that the dialog box performs a task of moderate
complexity). But that doesn't tell *why* you want to perform the task.

My own experience as a tech writer has often been that I have to
document something before I really understand why I would want to use
it. Especially if it's highly specialized or technical. And then over
a period of documenting parts of the total product, maybe at some point
the original purpose comes through in an "Aha" moment.

But you're really asking what's the purpose of software? Or maybe
what's the purpose of an interface?

The idea comes to mind of a coffee-vending machine. You push buttons to
select your beverage and have it dispensed by the machine. The very
same thing can be accomplished (the selection part, that is) with a
software GUI -- a dialog box. You select all the particulars of your
coffee or hot chocolate or whatever, and then an actual machine
dispenses it. The software merely takes your order (and conveys it to
the machine).

So I guess machines replaced humans, at least in the order-taking
process, and now software can replace machines (and people). I mean,
you can probably do all your ordering at Starbucks from a touch-screen.
Wouldn't be nearly as much fun, but probably faster.

I don't know, I guess we get so focused on how to use software that we
don't get a chance to think as much about why we use it, or a particular

Cool stuff -- thanks for posting, keep it up. Your recent rant, earlier
in this thread, was one of the best things I've read in a while.


PS - I know there are already touch screens for ordering and there are
vending machines with GUI interfaces. That's a preemptive hip-check for
anybody who wants to bag on me about such nonsense. There *are* such
people on Techwhirl. :) To all such people I say, chomp on your
teething ring and think about, "What's the purpose of MS Word?" :)


Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.

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:


RE: Click X, or click the X button?: From: Marguerite Krupp

Previous by Author: Re: Click X, or click the X button?
Next by Author: Click X, or click the X button?
Previous by Thread: Re: Click X, or click the X button?
Next by Thread: Re: Click X, or click the X button?

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

Sponsored Ads