Re: "use-case based documentation"

Subject: Re: "use-case based documentation"
From: Julie Stickler <jstickler -at- gmail -dot- com>
To: Technical Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 5 Feb 2015 12:22:44 -0500

Keith has a (valid) worry about writing documentation based on use cases,
that it might not match the final product.

Since we don't have use cases, design documents, or even what I'd call
proper user stories, I've been writing my documentation against the actual
state of the software that we're shipping, so no worries there. Oh the
joys of Agile!

But it's been very enlightening hearing that "use case based documentation"
should be based on something that I don't have at my job. Actual use
cases. *sighs* But at least I can go back to the Product Manager and say,
I'll be happy to base my docs on your use cases. Once you show me where
we've got said use cases written down for me to work with.

On Wed, Feb 4, 2015 at 9:26 PM, Keith Hood <klhra -at- yahoo -dot- com> wrote:

> The idea of basing documentation on use cases makes me nervous. It tells
> me the development team wants the docs written with only the use cases for
> source material. But there are ALWAYS gaps, bugs, shortfalls, and just
> plain mistakes between developing the use cases and cutting the gold
> master. There will be changes to the design that the technical writer will
> never know about until he sees the product itself, because the developers
> will all be too busy hunting bugs, or (happens all too often) they don't
> consider the tech writer really part of the team and they forgot he's
> there. Basing product documentation on any kind of design paper instead of
> basing it on looking at the actual product itself is nothing but a
> guarantee of documentation that is incomplete and out of phase with
> reality.There has never been an end-result product that actually works the
> way the design documents say it should, and I'll bet my entire next month's
> pay there never will be.
>
>
> On Wednesday, February 4, 2015 2:12 PM, Robert Lauriston <
> robert -at- lauriston -dot- com> wrote:
>
>
> On Tue, Feb 3, 2015 at 1:48 PM, Robart, Kay <Kay -dot- Robart -at- tea -dot- texas -dot- gov>
> 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.
>
> If they had that sort of formal document, Julie's manager could just
> point to it.
>
> Where I've worked, a use case is what one user would want to do with a
> particular feature. It's not necessarily written down anywhere, it
> might be just a point of discussion in meetings. One place I worked,
> they had a fictional set of named users: Angie is a manager and needs
> to do A, B, and C, Kevin is a case worker and needs to do C, D, and E,
> etc. I think people in that company had too much time on their hands.
>
> Agile user stories are similar, except that in agile the user story
> comes first and the developers write the feature to satisfy the
> associated acceptance requirements.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 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 klhra -at- yahoo -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
>
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 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 jstickler -at- gmail -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
>



--
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 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


Follow-Ups:

References:
Re: "use-case based documentation": From: Robert Lauriston
Re: "use-case based documentation": From: Keith Hood

Previous by Author: Re: "use-case based documentation"
Next by Author: Re: User Documentation Book Suggestions
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