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.
>...ONLY DFDs actually prompt you through a task analysis.
> How? By following the flows of data as they naturally
> combine and split apart, we flush-out essential tasks
> that may very well have gone undiscovered otherwise.
> And thats what analysis is: a discovery process.
This strikes me as unbalanced. Yet, it is familiar, like deja vu all over
again.
You are proposing that the tech writer synthesize significant understanding
of the project requirements and design. The discovery process you're
proposing leads to madness. But I think I know where you're coming from,
where tech writers are not in the requirements/design loop.
All of my efforts at this stage of a project are funneled into getting any
existing artifacts of analysis from the dev team. They're taking direction
from someone, right? I want to share in that direction, or I have nothing
to go on. What I need cannot be reliably detected, as ethereal traces of
undocumented analysis and design, in the finished product.
My experience points to this:
I think you're basically saying that an application 'computes' backward--you
can get traction on the requirements and design simply by diagramming what
you can see about an application, and through diagrams it will reveal what
you need to document. I feel like that is not how a tech writer adds value,
any more than an auto mechanic tunes your car engine by taking it apart and
putting it back together to make a few small adjustments.
IF you are saying that your discovery process (diagramming, iterative
reviews) is concerned with small adjustments to an otherwise fairly complete
view of the product, then fine. I could sign up for that, because as I
mention on my award winning web site, the SMEs have trouble seeing their
work through the end-user's eyes. They won't always take the time to plan
carefully what they say to you when you interview them.
But! if you're trying to do more than impose a little order on the
interface, or ferret out missing details in the offical account of
what/how/why the product does, then you probably will need to augment the
street smarts (you mentioned this) with bulletproof protective gear to CYA
when something goes wrong, and a locker full of investigate techniques
beyond Yourdon, and an accomplice on the inside who can get you the
requirements and design documentation, as documented for the customers in
development and on the business side of the house...
> Compare this with ALL other task analysis (note: same
> as functional analysis) modeling techniques -
> including Use Cases, all other UML functional modeling
> techniques, the hierarchal task analysis techniques
> espoused by the end-user task analysis community,
> logical (If-Then-Go-To) flow charts, task analysis
> techniques espoused by the QA community, on and on and
> on. With ALL these other techniques, we first draw
> boxes, or ovals, or stick men, or whatever to
> represent whatever tasks (functions) that happen to
> pop into our mind at the moment
The only way that you (the tech writer, with locker full of investigative
tools) will be in a position to discover the detailed requirements and
design of a product is if you have access to the already-completed
Requirements discovery process, which was *ideally* done and documented by
business analysts, product/data designers, solution architects, or whoever
is responsible for designing the system of inputs/outputs/processes that you
are concerned with. In terms of DFDs and such, this work gets done to
provide a clear paper trail of the analysis and reasoning that went into the
project. This is the serious detailed information that the business team
will consider when they compare the $$$ project price tag against the
expected benefits. This is the information they later review in project
post-mortems, in the quest for business goals like process maturity. I don't
know if your DFDs have any relationship to these, but I think it would be
miraculous if they did. Evangelical Yourdon zealots performing feats of
intuition and mind-reading daily! Wow. Forget tech writing. Give
seminars.
The bad news is, if discovery is the only tool available to you, then you
have first class butt-heads for co-workers. A project should have someone
who is designated as accountable for the requirements and design. That
person will be in it up to their ears, but they willl also have the power
and authority to go out and get the real requirements, and develop the real
design. Tech writers rarely get that kind of authority to pursue
requiremets and design. (But doesn't that sound the situation that leads to
the information "turf" issues you described?)
> It is very dangerous to be a DFDer because DFDs, like
> nothing else, enforce rigorous honesty and open
> communications. They get right to the meat of the
> issue: rigorous identification of essential procedure.
See what I mean? It isn't DFDs that are dangerous. Danger is doing the
analysts' job without asking them for the information you need.
> (See note below on essential procedure.)
> Problem is that, in business, knowledge of essential
> procedure is turf, and people will defend "their" turf
> to the death. The danger that a DFDer faces is that
> they are, on one hand, prodded to get the essential
> info; but, at the same time, they are prodded, big
> time, to ask questions that are often fearful.
Try asking for the person charged with discovering requirements and
designing solutions. At the very least, and if you have the right stuff,
you might penetrate to the real crux of the matter, which is why no one is
made accountable for writing requirements and design specifications that you
can use to learn all about the product.
> since the analyst is in the discovery phase, he/she
> often has no idea that a given question is so potent;
> it is very easy for him/her to step on a "political"
> land mind!
I've worked in places where no one would dream of asking about product
design during the discovery phase. If you find that this is happening at
your workplace, consider the remedial benefits of long lunches (compared to
spending more time in the minefields)..
> Another danger of using DFDs revolves around the fact
> that they are the only true top-down analysis
> technique. Top-down means that the analyst postpones
> detail(I said postpones - not forget about - big
>
This definition drifts too much for me. I think top-down means it proceeds
from a strong design. Top down means it is vertically-organized, with
authority at the top giving the orders. Top-down is a highly prescriptive
way to do things. Bottom-up is more about long lunches.
> The vast majority of people, including most IT
> managers, have always approach there work by jumping
> immediately into the details. They think: "Hey Tony
> has been doing task analysis for a week now, and he
> still does not know about detail X. I was here only a
> day when I knew about detail X. Therefore, Tony must
> be goofing off."
>
> All the above explains my saying: "It is only by dying
> (i.e., following the flow of data) that we are born
> again (i.e., come to have a understanding of the
> underlying logic of a system)."
If you love something, set it free ...
If you need something, take hostages...
> **Note On ESSENTIAL procedure: A ways back I read
> about a National Science Foundation study that
> concluded that only about five percent (5%) of
> procedure in any manual and/or automated system
> is truly essential. The rest just exists
> because of imperfect technology or imperfect
> design.
If NSF is so necessary, why doesn't the private sector do it?. If NSF is so
concerned with cutting things to essential operational requirements, maybe
we should be thinking of outsourcing NSF. Doh!
ROBOHELP X5 - SEE THE ALL NEW ROBOHELP X5 IN ACTION!
RoboHelp X5 is a giant leap forward in Help authoring technology, featuring all new Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! View an online demo: http://www.macromedia.com/go/techwrldemo
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -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.
