Use cases; was: Minimilism

Subject: Use cases; was: Minimilism
From: David Neeley <dbneeley -at- gmail -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Fri, 2 Oct 2009 09:30:28 +0300

Many popular or merely trendy techniques are applied by rote all too
often, to the detriment of common sense. We have seen how many may not
fully understand Carroll's concept of "minimilism".


Another, and a pet peeve of mine, is the wide variety of poorly
executed use cases.

One example that is unforgettable for me was when I was assigned to
ducument a new feature for a Nortel switch some years ago (obviously,
before they imploded). The engineering document had six separate use
cases, complete with tables and diagrams...yet it was completely
confusing. I struggled with it for hours to gain some clarity as to
the meaning of it all--it seemed illogical, somewhat contradictory
where it wasn't completely duplicative.

I diagrammed everything on a white board--putting each use case in a
different color. For nearly two complete working days, I struggled to
understand why it was such a convoluted explanation for what I
understood to be a fairly simple feature.

I even called the engineer--in India--to try to increase my
understanding. I realized that while he apparently was very good at
coding, his English was as arcane in speech as in his writing.

At last, comprehension began to dawn. The problem was mostly that he
was trying to stretch the feature explanation into every possible use
case he could--even though when it all came down to the essence, it
just wasn't so complicated after all.

The resulting document shrank the explanation of the engineering
document down from about thirteen very confusing pages to two, the
diagrams and tables from six of each to one of each. The diagram,
moreover, had four blocks connected in series.

The engineers of the field implementation unit--who were charged with
installing new software versions at selected customer sites to test
them in the field, told me they "finally understood" what the new
feature was all about.

I, too, spent much of my career alternating between marcom and tech
pubs. Both areas are occasionally known for rote application of poorly
understood concepts. The attempt to be "leading edge" often results in
frustration for all concerned...especially the poor customer.

David
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


Previous by Author: Re: client refuses content responsibility - Follow-up
Next by Author: Render farms; was: Re: Playing can you top that
Previous by Thread: Re: Word 2007 cross-references
Next by Thread: OT (I think): Free 30 day download CD for Adobe TCS2 - xposed to CIC SIG, Lone Writers, Framers, Free Framers, and RMC STC


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


Sponsored Ads