Constant 'Nonsense' about RR documentation

[David Burgun]

>>David Burgun wrote:
>>>>I learnt Hypercard without a book,
>>>>and I extended my knowledge, as RR extended xTalk, in the
>>>>same way:
>>>>
>>>>by doing!
>>>
>>>That's great if you have all the time in the world to "doing" it 
>>>wrong many times! Especially when the documentaion is just plain 
>>>wrong!
>>
>>As with the spelling of "documentation" in that sentence, human 
>>error can creep into just about anything.
>>
>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".

This is from the Answer command:

The prompt is a string (or any expression that evaluates to a 
string). The dialog box expands if necessary to fit the contents.

This just doesn't happen, in many cases it just gets chopped off. 
There are other instances, but I really can't be bothered to find 
them right now.

Actually I didn't particually mean RunRev in this case, I meant any 
system. The point I was making is that with other systems there is a 
"bible" you can refer to or many other sources of information that 
allow you to find the error, for instance, I have a book on C++ that 
is factually wrong, I hit that problem, I can look at a whole host of 
other C++ books or even the "White" book to see what is *supposed* to 
happen.


RunRev is different in this respect and many times no one seems to 
actually know what is *supposed* to happen and I get a number of work 
arounds to a problem (from this list mainly) that may or may not work 
in all situations.

I was also pointing out that the general pace of software development 
has changed over the past 25 years and that back then there was time 
for much more for Trial and Error than today.

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

A book or books like Inside Mac would be just fine as far I'm 
concerned, also a book like the K&R C book which defines what is 
*supposed* to happen would be good too. Something that is the LAW and 
if the implementation differs then it's the implementation that is 
wrong, not the documentation.
>
>But factually incorrect?  I'm sure there are errors in there, but no 
>more so than with any other documentation project of such scope, and 
>none that I can recall as related to the issues you've raised here 
>recently.

There are quite a few instances that I have found  in the docs that 
are factually incorrect. This can happen I agree as with anything 
human. The thing is that in the case of the answer dialog it has been 
known about for a long time it seems. We have just had a new release 
of RunRev but the documentation was not changed. This is the problem, 
not that there are errors in the docs, just that they are not fixed 
or updated promptly either to make the code match the docs or the 
docs match the code.



My Dairy of RunRev is a lot simpler!

Day One: This is just GREAT I Love it!

Week 3 - Why are there so many silly problems with it that spoil the 
experience?

Month 18 - Why are there so many silly problems with it that spoil 
the experience?


Take Care and All the Best
Dave