Constant 'Nonsense' about RR documentation

[Kay C Lan]

On 11/30/05, Richard Gaskin <ambassador at fourthworld.com> wrote:
>
>
> While there's always room to expand on the material that's there, I
> don't recall any recent issue you've raised here in which the
> documentation was "just plain wrong".
>
> Sure, some sections could be expanded to address a wider range of needs,
> and for the love of Koresh I'd love to see a new TOC.
>
> But factually incorrect?
>

>From my perspective I see two areas for improvement.

That all examples actually work!

Now before you come back and ask 'give an example', I would suggest that for
99% of newbie's if they cut and paste most functions into their stacks they
wont work. For you they will because you instictively prefix the statement
with 'put' and generally postfix it with a variable to store it so it
doesn't become lost in 'it'. In my short time on this list I've seen two
gentle pointers on how to deal with functions for newbies who can't get them
to work.

For the impatient, those who haven't found this list or do not have access
to it, and those who haven't mastered the dubugger, how much hair pulling do
you factor in before you think they'll conclude - too hard.

If the documentation actually had examples that you could cut and paste into
a stack, osmosis would take care of the rest, no more posts to the list
asking something very basic. Amending the docs to include 'put' and a
sensible variable name isn't that hard.

The other area is searching the documents. All the information is very very
good, but I, and I notice alot of others in their posts, sometimes have
trouble finding it. What really irks me is when I've found the information
and a day or two later I try to go back to it and I just can't find it. I
can't remember the search or filter pattern that was 'just right'. I notice
that you include a better TOC, which is just another way to search.

I also have a problem with the TOC, although it might be my set up because I
know Xavier reported that he wasn't suffering what I do, but if I open the
documentation, click on Topics so you have the TOC in the left field, then
click on one - in this case lets say 'Custom properties, and...' it takes
around 10 seconds !!! before the right field is built, and at no time does
the cursor change to busy - it just looks like nothing is happening. For
quite a long time I was too impatient (although 10sec is too long) and would
click off else where. How many others suffer this and do not actually get
into the docs because they're just too slow.

If I'm the only one with slow access to the doc's I'd love to know how to
fix it:-)