Re: "use-case based documentation"

Subject: Re: "use-case based documentation"
From: Hannah Drake <hannah -at- formulatrix -dot- com>
To: kafkascampi <kafkascampi -at- gmail -dot- com>
Date: Wed, 4 Feb 2015 08:40:28 -0500

Hi all,

Agree that the PM seems a bit confused as far as terminology. I'm a PM and
the documentation lead, and we are implementing scrum, so this question is
right up my ally.

If you think about it from a scrum perspective, use case would mean this:

Story (aka use case): as a (role), I want to use the software to create X,
so that Y.

Then you would take that mission statement and break it into what you need
to do documentation wise to ensure they can compete the goal. So this might
mean:
-easily accessible help topics, indexed and searchable, linked together
that explain the following: (etc)
-screencast to explain more complicated features of X
-links to several predicted next steps such as (etc)
-information on common error or stumbling block

So, my advice would be for you to provide your own example of "task based"
vs. Use case/story based - the latter is more of a management technique and
primarily helps to drive organization and understanding. The former is, as
you know, and actual style do tech writing driven by tasks and not
cluttered with conceptual explanations, which are usually presented
elsewhere in the documentation.

Typical PMs don't know much about tech writing, but the position usual
requires a ton of management application and knowledge. So my guess is
nobody is wrong here, but if they do in fact mean the scrum style stories,
it would require sign off from them before you began the actual technical
writing on the story. Make sense?

On Tuesday, February 3, 2015, kafkascampi <kafkascampi -at- gmail -dot- com> wrote:

> Robert said "Well, a use case is sort of task-based, but it shows all the
> activities that a user wants to perform as well as alternate actions and
> the behavior of the software."
> ----
>
> I'd say use-case based documentation would be an end-to-end for a specific
> objective. Like "Sheila wants to use the Fintoozler 5000 to outsource her
> wombats". This would be a sequential set of tasks to achieve that end. At
> least that's what PM would mean if they asked me for that. I think the
> tension here is between a minimalist approach of specific task-oriented
> documentation and a more holistic "the user wants to get XXX done."
>
> If you write in task - concept - reference, you might have the tasks
> required for Sheila to outsource her wombats, preceded by a concept that
> gives the overview of how these tasks work together to make that possible.
>
> Chris
>
> On Tue, Feb 3, 2015 at 2:14 PM, Scott Turner <quills -at- airmail -dot- net
> <javascript:;>> wrote:
>
> > From the OP, it really sounds as though the products after is using buzz
> > words, and that she dimly understands the meaning behind them.
> >
> > Scott T.
> >
> >
> > > On Feb 3, 2015, at 15:48, Robart, Kay <Kay -dot- Robart -at- tea -dot- texas -dot- gov
> <javascript:;>> wrote:
> > >
> > > Well, a use case is sort of task-based, but it shows all the activities
> > that a user wants to perform as well as alternate actions and the
> behavior
> > of the software. However, use cases are usually produced as part of the
> > requirements process and are written by the business analyst. They aren't
> > very useful to anyone except software designers. I haven't even found
> them
> > very useful for trying to figure out new software and documented it. Is
> she
> > asking you to do the business analyst job? Or maybe she doesn't really
> > understand what she's asking?
> > >
> > > -----Original Message-----
> > > From: techwr-l-bounces+kay -dot- robart=tea -dot- texas -dot- gov -at- lists -dot- techwr-l -dot- com
> <javascript:;>
> > [mailto:techwr-l-bounces+kay.robart <javascript:;>=
> tea -dot- texas -dot- gov -at- lists -dot- techwr-l -dot- com <javascript:;>] On
> > Behalf Of Julie Stickler
> > > Sent: Tuesday, February 03, 2015 11:48 AM
> > > To: Technical Writing
> > > Subject: "use-case based documentation"
> > >
> > > One of our Product Managers keeps using the phrase "use-case based
> > documentation" as in, that's something she wants the doc team to provide.
> > > I suspect what she means is task based documentation, but she insists
> > that's not what she means.
> > >
> > > However, she has so far failed to provide me with an example of what
> she
> > wants.
> > >
> > > Anyone out there ever provided use-case based documentation? Got any
> > good blogs posts, articles, presentations, or examples so I could get a
> > better idea of what exactly she's asking for?
> > >
> > > --
> > > Julie Stickler
> > > http://heratech.wordpress.com/
> > > Blogging about Agile and technical writing
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy
> > & Procedure Guides, eBooks, and more using Microsoft Word |
> > http://bit.ly/doctohelp2015
> > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > >
> > > You are currently subscribed to TECHWR-L as kay -dot- robart -at- tea -dot- texas -dot- gov
> <javascript:;>.
> > >
> > > To unsubscribe send a blank email to
> > > techwr-l-leave -at- lists -dot- techwr-l -dot- com <javascript:;>
> > >
> > >
> > > Send administrative questions to admin -at- techwr-l -dot- com <javascript:;>.
> Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources and
> > info.
> > >
> > > Looking for articles on Technical Communications? Head over to our
> > online magazine at http://techwhirl.com
> > >
> > > Looking for the archived Techwr-l email discussions? Search our public
> > email archives @ http://techwr-l.com/archives
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy
> > & Procedure Guides, eBooks, and more using Microsoft Word |
> > http://bit.ly/doctohelp2015
> > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > >
> > > You are currently subscribed to TECHWR-L as quills -at- airmail -dot- net
> <javascript:;>.
> > >
> > > To unsubscribe send a blank email to
> > > techwr-l-leave -at- lists -dot- techwr-l -dot- com <javascript:;>
> > >
> > >
> > > Send administrative questions to admin -at- techwr-l -dot- com <javascript:;>.
> Visit
> > > http://www.techwhirl.com/email-discussion-groups/ for more resources
> > and info.
> > >
> > > Looking for articles on Technical Communications? Head over to our
> > online magazine at http://techwhirl.com
> > >
> > > Looking for the archived Techwr-l email discussions? Search our public
> > email archives @ http://techwr-l.com/archives
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy &
> > Procedure Guides, eBooks, and more using Microsoft Word |
> > http://bit.ly/doctohelp2015
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as kafkascampi -at- gmail -dot- com
> <javascript:;>.
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com <javascript:;>
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com <javascript:;>.
> Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources and
> > info.
> >
> > Looking for articles on Technical Communications? Head over to our
> online
> > magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions? Search our public
> > email archives @ http://techwr-l.com/archives
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy &
> Procedure Guides, eBooks, and more using Microsoft Word |
> http://bit.ly/doctohelp2015
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as hannah -at- formulatrix -dot- com
> <javascript:;>.
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com <javascript:;>
>
>
> Send administrative questions to admin -at- techwr-l -dot- com <javascript:;>. Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Doc-To-Help: The Quickest Way to Author and Publish Online Help, Policy & Procedure Guides, eBooks, and more using Microsoft Word | http://bit.ly/doctohelp2015

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

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-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
"use-case based documentation": From: Julie Stickler
RE: "use-case based documentation": From: Robart, Kay
Re: "use-case based documentation": From: Scott Turner
Re: "use-case based documentation": From: kafkascampi

Previous by Author: Re: Proofreading your own material
Next by Author: Need your help - we (Al and Connie) would like to present at LavaCon
Previous by Thread: Re: "use-case based documentation"
Next by Thread: Re: "use-case based documentation"


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

Sponsored Ads


Sponsored Ads