Re: Click X, or click the X button?

[Marguerite Krupp <mkrupp128 -at- yahoo -dot- com>]

Right on, Chris!

My only quibble is with your statement that you should share all this info with your customers. I think a certain amount of discretion/filtering is required, because as an "insider," you know more detail than your users need to know. In the classic phrase, if I want to know what time it is, I don't usually want to know how to build a watch. We get paid for knowing what users need and providing it.

One of the gotchas with Agile is that often the product evolves, rather than being designed, so it's virtually impossible to know all you need to know to write the docs when you start writing them. That's why the communication part and the focus on the user stories are so crucial. Further, they build one feature at a time, which also affects what/how you write.

Now I've gotta get back to actually doing it! <G>

Marguerite

--- On Wed, 10/28/09, Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com> wrote:

> From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
> Subject: Re: Click X, or click the X button?
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Date: Wednesday, October 28, 2009, 10:48 AM
> 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.
> 
> Also,
> 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.  
> 
> As
> 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?
> 
> You
> 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.
> 
> cud
> 
> 
> 
> 
> ________________________________
> 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!
> 
> Marguerite
> --- 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
> day.
> 
> 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
> app.
> 
> 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.
> 
> Steve
> 
> 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.
> http://www.doctohelp.com/SuperPages/Webcasts/
> 
> 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 mkrupp128 -at- yahoo -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/mkrupp128%40yahoo.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
> 
> 


      
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.
http://www.doctohelp.com/SuperPages/Webcasts/

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- 

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