Another Area For Document Development

[Thomas McGrath III]

Actually, for me I want and prefer both documented searchable documents 
(electronic) and printed documents to peruse through and or flip 
through when I am not sure of the name or concept I am looking for.
I also download as many sample stacks as possible to see how others 
have treated a specific topic or question. However each of these has 
faults as well. If you don't know the exact word/phrase you want then 
electronic docs don't help. If you know exactly what you want then 
printed docs are slower than the electronic and can be a bit bulky to 
use. (You can't take them on the road.) Stacks are not easily 
searchable and must include more code than what will solve the problem 
you are looking for in order to work (good and bad here).

A combination of all three is what I use and what I look for. I tear 
apart peoples code to see how they do it. I read the printed docs in a 
browsing way to get ideas on more than one topic and also to see that 
topic in its entirety. I use the electronic docs to quickly look up the 
exact syntax for an item and see related items quickly right from 
within REV.

I think more descriptive samples in all of these is a good thing. I 
want to see more than two possible examples for each code. If it can be 
used with get and put than I want to see one of each etc.

AND stop using the word itself to describe the word. If I don't know 
what the word means then using it in the example is not going to help.

FWIW

Tom

On Apr 5, 2004, at 1:07 PM, Judy Perry wrote:

> 1.  People hate reading manuals/documentation (it can be confusing and
> frustrating for the very reasons you outlined even IF typing in 'tab
> buttons' revealed anything).
>
> 2.  The documentation isn't visual, so even providing a cookbook script
> doesn't tell you how to go about implementing it in a meaningful way
> (especially if you are a nonprogrammer).
>
> 3.  Sample stacks put the items in both a visual and  contextual frame 
> of
> reference.  People can look at the item, look at the script, and 
> observe
> the output without having to look at a page of code and then try
> copy-pasting or typing things in and hoping one got everything together
> where it was supposed to be).
>
> 4.  Sample stacks provide for code reuse and modification -- the latter
> encourages the new programmer to experiment with the scaffolding of
> keeping the original goodie intact.
>

Thomas J. McGrath III
SCS
1000 Killarney Dr.
Pittsburgh, PA 15234
412-885-8541