Re: Not being a programmer...(long)

[John Posada <jposada01 -at- yahoo -dot- com>]

> I would bet that most (or ALL) of the programmers don't know what
> all those files are either.

Keep in mind, I'm creating internal documentation that describes a
large Human resources web portal for use by technical prople...the
company hires a programmer, developer, systems analyst and they give
the person my manual to get them up to speed, or a developer in one
module want to see how a developer in another module approached
something. 

One of the other disadvantages with not being a programmer is that
you try to think like one when structuring the doc, but ya don't know
if you are at the right depth of detail.

For example...and I'm tying this in with the thread about the SDK
documentation thread on slashdot. There is a comment:

"...Personally, I like nothing better than code examples, and lots of
them. I've never really used a SDK, but I have done enough
programming in different languages to know what helps me turn out
productive code quickly. ..."

In my docs, I'm documenting, in addition to the way it works and the
flow of data and the flow of processes, the use of .asp, dll, stored
procs, databases, triggers, etc.

Example: In my doc set, I have a data dictionary, and each time I
mention a database table, I link to the entity ERD, then from there,
the dictionary, then from there, the SP and trigger codes, along with
the syntax, parameters, properties, called procedures, "applied to"s,
anfd then the actual and complete code. 

Not only is this laborious, but it comsumes LOTS of pages. When you
consider just for ASP code alone, there are maybe 700 asp web pages
in the system and the code is minimum of a page, and sometimes 3-4
pages (or more). 

Add several hundred SPs, and the doc sets becomes VERY large.

My question...does any of this help you when you are a techie? Do you
care to see 3 pages of stored procedure?  My quess is that if it
takes 30 seconds to find it in the doc and a minute to crank up
Enterprise Manager or VSS, you'll go to them, but if it takes 3
minutes for the ap, you'll probably look at it in the docs.

Now, don't misunderstand...I don't just puke content. For example,
with my data dictionary, when you click a link in the doc, you get
the ERD. At the bottom of the ERD, I include links to the entity
data, and from the entity data, there are links to the stored procs
and trigger codes for that entity. The idea being to create a "data
web" (?).

What I'm asking, and this is directed toward those writers who ARE
programmers, does this depth of detail help, hinder, or just make you
go "no help for me".


John Posada
Senior Technical Writer

?Never be afraid to try something new. Remember that a lone 
amateur built the Ark. A large group of professionals built 
the Titanic.? - Dave Barry

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WEBWORKS FINALDRAFT - EDIT AND REVIEW, REDEFINED
Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:
http://www.webworks.com/techwr-l

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