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.
That's what Use Cases are for, and are perfect for a technical writer to
do.
Use cases are requirements expressed in action process steps performed
by the user and the system (as well as where they "touch" any ancillary
systems).
Use cases can be either "black box" (we don't care what the system is,
and don't describe what the system does inside, just the input and
output) or "white box" (we describe the internal system actions, as well
as describing the input and output). A use case includes actors (users
and systems of different types) and steps to a process using the system
under development and the requirements. These are usually done in
tables, which I can't do in plain text, but have used hyphens to show
the column breaks. For example:
Actor: General User
System: Our System
Premise: The general user will be able to login and retrieve their
messages in OurSystem.
Steps:
Actor - Step - Action
General User - 1 - Logs in to OurSystem with GUID and password.
OurSystem - 2 - Receives GUID and Password.
OurSystem - 3 - Matches GUID and Password to user list. Is it a known
user? If Yes, proceed. If No, Stop, and send message to screen "Login
not allowed," and message to log file (logfile.txt) Unknown user, GUID,
Date, Time.
General User - Login is accepted. Selects message area.
Etc....
Anyway, that's a short version.
Here are some of the books that have used for writing good use cases,
all available through Amazon.
Use Case Driven Object Modeling with UML : A Practical Approach
(Addison-Wesley)
The Rational Unified Process: An Introduction (2nd Edition)
Writing Effective Use Cases
Use Cases: Requirements in Context
The last two are *excellent* and very easy to follow. Additionally, when
the use cases are done, you can use them as a basis for user guides,
system guides, and so on.
Diana Ost
Technical Writer/Reporting Analyst
This message and any attachments may contain confidential or privileged
information and are only for the intended recipient of this message. If
you are not the intended recipient, please notify the sender by return
email or phone, and delete or destroy this and all copies of this
message and all attachments. Any unauthorized disclosure, use,
distribution, or reproduction of this message or any attachments is
prohibited and may be unlawful.
> -----Original Message-----
> From:
> techwr-l-bounces+diana -dot- ost=msmcorp -dot- com -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+diana -dot- ost=msmcorp -dot- com -at- lists -dot- techwr-l -dot-
com] On Behalf Of Beth Agnew
> Sent: Wednesday, August 23, 2006 10:19 PM
> To: Ladonna Weeks
> Cc: techwr-l -at- lists -dot- techwr-l -dot- com; Myers, Jim
> Subject: Re: Software requirements
>
> A good working process is requirements (what the product, any
> product, is supposed to do to meet the needs of the market)
> first, then specifications (details on how the product is
> going to match each requirement), and finally design, which
> is the manifestation of the requirements according to the
> specifications. Test cases, i.e., QA, usually ensure that the
> product meets specifications. I don't think you can
> adequately capture such design features as you're talking
> about without indeed getting into the details. The thing has
> to become very detailed and specific at some point. Leaving
> requirements up to the developers to interpret is fraught
> with problems. Much better to hammer out the specifications
> which detail the design, so that all the developers have to
> do is build it. If they run into an implementation problem,
> such that they cannot build to specification without changing
> the design, then there should be a process for working that
> solution through the requirements/specifications/design
> process. All kinds of insanity result when developers just
> change things as they go along.
>
> Making specifications afterward based on the designed product
> seems to me to go at things wrong way round, but a lot of
> companies do that to ensure their specifications are correct.
> Of course, you then get what the developers have decided
> you'll get. Hope you've at least got a business analyst and a
> systems analyst working with them on that.
>
> The marketing requirements in the example you gave would be
> that the customer needs to be able to pre-determine a time
> period during which a random reboot will occur.
> Specifications say that this can be any time period from 1 to
> 24 hours, with a default of a 5 hour period. Your #3, the
> 10:00 a.m. local time, actually conflicts with the first two.
> It is not random, nor is it a period, but a fixed point in
> time -- but perhaps it's related to something else and not
> the first two points.
>
> I'm a firm believer in detailed specifications. Very few
> products go wrong when the specifications are thorough,
> detailed, completed, and followed. It's when the specs and
> the design get out of sync that problems occur.
>
> Ladonna Weeks wrote:
> > One of my TW duties is to help with an internal web site
> that contains
> > requirements for our new product.The requirments are stated in very
> > general terms in order to leave opportunity for the developers to
> > design the product. Here are a few examples:
> >
> > 1. It shall be possible to set a time period during which the
> > [product] will reboot at a random time during the set time period.
> > 2. The set time period shall be from 1 to 24 hours. Default
> shall be 5.
> > 3. Default time shall be 10:00 AM local time.
> >
> > We are writing a test case for each requirement. However,
> we have come
> > to realize that during testing we need some kind of specifications
> > that describe the behavior of the product as it ends up
> being designed
> > so that something in the GUI or functionality doesn't get
> accidentally
> > changed after the customer has become accustomed to it. The person
> > writing the requirements has come up with the notion of including
> > design features after the fact which describe how the
> product works.
> > When we test, we would test against the requirements _and_
> the design features.
> >
> > I am trying to figure out how to write these design
> features without
> > getting buried in details. Have any of you dealt with a
> similar problem?
> --
> Beth Agnew
> Catch the Buzz: http://bethbuzz.blogspot.com STC Presentation
> archived at:
>http://www.301url.com/podcasting
>
> Professor, Technical Communication
> Seneca College of Applied Arts & Technology Toronto, ON
> 416.491.5050 x3133 http://www.tinyurl.com/83u5u
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> WebWorks ePublisher Pro for Word features support for every
> major Help format plus PDF, HTML and more. Flexible, precise,
> and efficient content delivery. Try it today!
>http://www.webworks.com/techwr-l
>
> Easily create HTML or Microsoft Word content and convert to
> any popular Help file format or printed documentation. Learn
> more at http://www.DocToHelp.com/TechwrlList
>
> ---
> You are currently subscribed to TECHWR-L as diana -dot- ost -at- msmcorp -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/diana.ost%4
0msmcorp.com
>
>
> To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
>
> Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
>http://www.techwr-l.com/techwhirl/ for more resources and info.
>
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
