RE: Quality of source material from Development

["Eric J. Ray" <ejray -at- raycomm -dot- com>]

Whew. I was afraid I'd have to write all this up, but
was saved the trouble:

On Wed, 12 Dec 2001, Andrew Plato wrote:
> Blah blah - acronyms -- blah blah - Salan, I emphathize with your
> situation but throwing out a lot of acronyms and being intimidated by
> products is part of the game. Its not just about knowing the code or
> having a bigger SQL Server than the next guy, its about having the
> intellectual tenacity to cut through all the gibberish and make sense out
> of complexity. That's what a technical writer does!


The following is a GREAT example of how to dissect a technical
problem--sure, you have to have a broad background, but as soon
as you get the fundamentals and figure out which pieces are
generalizable and which are unique in a given situation, this is
EXACTLY what you do. (Note to people in a new environment
or contractors: Verbalize this process when you're being
introduced to the technology and you'll find your job just
got 100% easier, 'cause the engineering staff will work
with you more effectively.)

>
> SQL Server and Oracle are the same base technology they just have
> different bells and whistles. Lump them together. WinCE and WinNT - same
> story, different API. This is the OS. Radio waves: just a network
> transport layer. C/Pascal: Who cares what its coded in. What does it do?
> What goes in, what comes out? What it this products reason for existing in
> the universe?
>
> Basically its a big client/server problem Salan. People tap stuff into a
> PDA, it authenticates against some server somewhere, yanks data out of a
> database (that means somewhere there are queries and stored procs), feeds
> it back to the PDA and displays the information in some client app.
>
> So you've got installation issues, got some database transport issues,
> network connectivity, probably some reports, some data munging...basic
> client/server application.

And that's your 100 word course in _technical_ technical writing.

> Demanding the engineers essentially do your job for you is not going to
> earn you any brownie points and sure as sh*t won't get the docs written.
> You need to see the forest AND the trees, simultaneously. That isn't going
> to happen if somebody else is doing the "hard thinking" for you. You need
> to internalize the information, learn the products, and see the big
> picture.

The other piece that Andrew didn't mention is that you
might well be overworked. You might have too much to do.
You might not have time to come up to speed. So, you talk
to your boss and point out that you can either be
dependent on the engineering staff to draft your docs for
the foreseeable future, or someone can make hard choices
about what does NOT get done, so you have time to remediate
your technical knowledge, so you can contribute more
effectively in the future. Try it.

Eric



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Eric J. Ray                  ejray -at- raycomm -dot- com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,000 retailers.  And it's
affordable.  Join our almost 10,000 published authors today.
http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.