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.
What you wrote made me shake my head in near disbelief, but I'm glad you
wrote it.
Engineers writing use cases?
I'm sure that we've all been in a position where we have to write
documentation for a project that is closer to going live, than initiation.
This is what I was faced with. I wanted to write the business requirements,
functional requirements and business use cases concurrently, but mass
confusion prevented this. The business use cases have been written, and
these are what the developers are going to use to begin programming.
To further complicate things, upper-management wanted the BUCs to be
readable by both the stakeholders and the developers. Lucky me.
My BUCs are, well, pretty damn good. Abstract, the
Who/What/Where/When/Hows, task activities, data fields, GUIS, etc. It's a
lot of information, but it's clearly demarcated and different audiences know
where to go to get the information they're looking for.
Today, however, I have to work even more info into my BUC (see 'lucky me'
above). Using terms we all know, I have the following situation: 12
departments use our A1 system (we'll call it YouTube). To access YouTube,
11 of these departments use FTP (we'll call it IE7). The 12th department
uses Firefox. I'm thinking that I can simply note this in the BUC and, in
the Appendix section, include the data fields for Firfox, etc. (as opposed
to writing a separate BUC).
"Have you thought about doing use cases (from the user perspective) as
requirements for your new application? The use cases would be the foundation
for the user guides and other documentation, and would also provide the
developers with real world information about how the user would interact
with the new system. This would not require getting "permission" either,
since you would be using them as a tool to base the user documentation on."
As with any other technique I can think of, use cases can be very
poorly done--and many engineers are told they "must" produce use cases
when they see no point, then do a fairly slapdash job of it. The
result, rather predictably, can be something that is of no earthly use
to anyone.
When I had to document a single new feature for a telecommunications
switch, I was given such useless use cases. There were six, but it
took me two days to figure out what the engineer was saying. In the
end, I reduced the six diagrams he included to one, much simpler
one--with a page and a half of description that was far more clear
than his fourteen pages of use case muddle. I remain convinced that
the use case examples made things far more confusing and complex than
it ever needed to be. Had there been another engineer involved, it
also could have led to confusion in the implementation.
For any strategy, technique, or development methodology--whatever the
tools you choose to use--it is very helpful to get a full and
(hopefully) enthusiastic buy-in on the part of everyone involved in
that process.
Otherwise, the development will be far less than optimal, to put it mildly.
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
