RE: Quality of source material from Development

[Salan Sinclair <salansinclair -at- shaw -dot- ca>]

I asked a question in my attempt to produce quality documentation as
efficiently as possible.
You are using the question to grandstand yet again.

Yes, Andrew, some writers complain a lot.
Whether they complain *too much* is a matter of debate.

Yes, Andrew, some writers are less technical than you are.
Whether they should *all* be as technical as you are is a matter of debate.

Yes, Andrew, some writers have a different approach to documentation than
you do.
Whether you have the *best* and *only* approach is a matter of debate.

Please, get over it, and try to offer something new and constructive.


-----Original Message-----
From: Andrew Plato [mailto:intrepid_es -at- yahoo -dot- com]
Sent: Wednesday, December 12, 2001 3:21 PM
To: techwr-l -at- lists -dot- raycomm -dot- com
Cc: salansinclair -at- shaw -dot- ca
Subject: RE: Quality of source material from Development



"Salan Sinclair"  wrote...

> Andrew: Get the source code, read it, figure out what the commands are.
>
> Salan: Could do, but far fewer manuals would get produced because of the
> time required to figure out the code.

Like I said...its a blame loop. If you never figure out the code, you'll
never be able to pull information out of it, and as such you'll always be
doing things "the hard way."

Whoever said Andrew doesn't like processes? :-)


> Andrew: Everybody faces this problem. This isn't unique to your group.
> Why would your company deliver documentation to customers for a product
> before it is functional? That makes no sense what so ever. Isn't there a
> beta cycle? Testing?  I mean, I understand writing about something that
> hasn't quite been put together yet, but releasing docs to the public
> before there is a working product is totally inane.
>
> Salan: I said delivered "for review". Yes, there is a beta. The books
are
> expected to be complete and accurate for delivery to customers at beta.
And,
> if you have 2 writers and 10 books, some books have to be done *before*
> beta. It's simply a matter of days verses pages.
> We're talking about a development team of about 40 developers working
for
> year to create a new product, and 2 tech writers working for 4 months to
> document the entire thing.

So they were developing it for a year, but you only worked 4 months? What
was going on the other 8 months of that year?

> Andrew: If writers focus on learning the core technologies, they can
become
> expert
> users.
> If they focus on commas, FrameMaker and fonts - no. They will likely be
> lost in a sea of confusion and churn out crappy documentation.
> This is a case where style takes a back seat to substance. Focus 99.9%
of
> your energy on the substance of the documentation (content) and don't
> worry about the layout, design, etc. In the end you'll have good content
> that can be cleaned up later or cleaned up by a $18.00 an hour intern.
>
> Salan: Please don't simply assume that I care only about commas and
design.
> That is not the issue. I have taken several programming courses. I call
> myself a 'wanna-be programmer' at times. I read about every subject I
have
> to document. I want to know everything I can. But we're talking about a
> highly complex product and a highly technical audience. It would easily
take
> a "technical" technical writer 2 months to become proficient in each
> product, and there are 5 of them for each writer.

So what are you waiting for? Get crackin' on that code! Knowledge begets
knowledge. I find it hard to believe that every product your firm makes is
so fundamentally different that there is no similarities between each that
cannot be leveraged for each subsequent document.


> Andrew: A good writer who understands the technologies is able to
accurately
> anticipate functionality and use and therefore isn't "guessing". Those
> guesses are based on experience, knowledge, and a keen understanding of
> what your company's products do.
>
> Salan: Let's test your statements against specifics. The product I was a
> lone writer for included  real-time software applications written in
Pascal
> and C++ communicating via radio to dispatch mobile devices using Windows
CE
> and firmware. At the core were databases created in FoxPro, Oracle, and
SQL
> Server. It had 5 or so client applications written in Access and VB to
> access the databases for reporting, inquiries, and data editing. And
that
> was just the core system, not the add-on modules designed for specific
> customers. The documentation had to tell people how to install and use
about
> 10 products in various settings on various platforms. It also had to
tell
> people how to install, configure, upgrade, maintain, backup and recover
all
> three types of databases. The new Development Manager, with a PH.D, took
a
> year and half before he could say he actually understood the entire
product.
> I know some VBA and VB, can create Access databases and forms,
understand a
> fair bit about database design, and am "familiar" with all of the
> technologies listed. I was learning more everyday. I was gradually
learning
> Crystal Reports, SQL, and Windows NT server, etc, etc, but I was usually
too
> busy to make much progress. Each release, which occurred every few
months,
> would require a new document or help system for a new product, as well
as
> updates to about 10 documents in two versions (Oracle and SQL server).
There
> is no way I could get information in time by researching the code.
> I often agree with your posts, Andrew. I just not so sure that what you
are
> saying works in low-staffed situations with highly complex (or let's
say,
> diverse) products, especially if a writer is only there for 6 months or
a
> year.

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!

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. Now,  I don't have a PHD or know dick about
your products and I figured all that out. How'd I do that?

Well, I've documented about a thousand of these types of applications and
they're all about the same. Blah blah ...oh this one uses RPC instead of
SNMP right...blah blah blah...oh blue buttons instead of white....blah
blah...its the same story over and over again, just different characters
and bigger budgets.

Hand it over, I could doc this in 2 hours and on an empty stomach.

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.

Yeah, maybe you're overworked. Welcome to the club. Life's a turd sandwich
and everybody's got to take a bite someday.

Andrew Plato

__________________________________________________
Do You Yahoo!?
Check out Yahoo! Shopping and Yahoo! Auctions for all of
your unique holiday gifts! Buy at http://shopping.yahoo.com
or bid at http://auctions.yahoo.com



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
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.