Constant 'Nonsense' about RR documentation

[David Burgun]

>Hi Dave,
>
>Le 30 nov. 05 à 16:14, David Burgun a écrit :
>
>>>Hi Dave,
>>>
>>>Do you know what kind of book would represent the docs?
>>>In front of me are 2 A4 books (I need my glasses to read them :-) 
>>>which were sent to me by Runrev with Rev Enterprise 2.0.
>>>The first one (User Guide) is 370 pages and the other (Transcript 
>>>Language Reference) is 570 pages...
>>>I think that maintaining the docs is a hard work: you could have 
>>>some good surprise with the Rev next version :-)
>>
>>Have you seen the Apple Inside Mac Books?
>
>In front of me too :-)
>But it's difficult to compare books coming from a more than 20 years 
>company counting several thousands of "employees" and Runrev :-)
>May be one day?

Yes, I agree, but then this isn't as big as Apple/Mac. It's 
equivilent to say AppleScript, QuickTime and the FIle System. As I 
said, I reckon it could be split into somewhere between 5 and 10 
books.

>
>>It must be as hard or harder to maintain the online docs that 
>>seperate PDF files.
>
>The docs are stored into XML files (about 1740 for the dictionnary, 
>500 for the faq, etc.).
>Data are of course not in the stack. So maintenance should be appear easy...
>Have a look in the components/help folder.
>
>>If they made say broke it down into (say) 7 books, it shouldn't be 
>>so hard to do. And as long as the latest updates were available 
>>online. I am not necessarily talking about a printed books 
>>(although that woukd be nice!), downloadable PDFs would be just 
>>great.
>>
>>For instance, for RunRev Version 3, wouldn't it be nice is the 
>>books for it came out way ahead of any code being produced. The 
>>docs could then be proof read by people on this list and as many 
>>errors etc. fixed.


>
>This would mean that you should have to be a beta tester too: don't 
>you have enough issues with released versions?
>If I understand correctly :-)

That would be a good thing! Beta testing is just fine, yes the 
"Bible" should go through a similar process too.

I'm not sure what you mean biut issues with released versions? The 
only thing I have problems with is new features being added when bugs 
that have been there for a long time are not fixed.
>
>>This would become the bible and could not be changed without RFCs 
>>like the internet committee.
>>
>>The implementation would then come from this bible and anything 
>>that differed from the bible would be considered a bug and fixed, 
>>unless an RFC is raised and passed.
>>
>>Of course this could/would mean that creativity is stifled in terms 
>>of adding new features, however this need not be the case. As long 
>>as the Standard RunRev 3 "Bible" was left as defined, there could 
>>be extensions that added to the language, similar to the way in 
>>which #pragma's work in C/C++, adding to the standard , but never 
>>actually taking the "standard" away.
>>
>>Eventually these extensions would either die out or be adopted back 
>>in the standard on the next major revision.
>>
>>I really do think that something like this just has to be done if 
>>RunRev is to really make it into the mainstream.
>
>Something like that will happen for sure but needs a bigger 
>community first: so, stay with us :-)

Well, to me this is a chicken and egg situation, it can't get bigger 
til the above is done and that can't be done til it gets bigger.

What it needs is some investment! How much do people on the list 
think it would take in terms of money to put this into place? I'd be 
happy to cough up $100 or so if I thought the above would be done. 
This would be credited back to to those who contribute in terms of 
free updates to the docs and (maybe) free renewal of license fees.

(I've already spent far more than that in terms of wasted time!)

Anything just to move this forward, it's been hanging around in the 
slow lane for too long. If something isn't done soon a similar tool 
will come along and wipe it out.

I know some (if not most) of you on this list have had past 
experience with MC and it's kin, but I haven't and to be honest I 
have no loyalty in terms of history to motivate me (unlike say Apple 
or the Mac Plaftform), if something like rev came along, even if it 
only had 75% of what RunRev has now but all the above was 
implemented, I'd jump boat. Since I would really have more to put my 
faith in, in terms of getting to a mainstream product.

Having said that, I suppose I do have *some* loyality to RunRev Ltd., 
since I admire (mostly) what they have acheived so far. I have also 
worked a founder member of a number of companies and know all about 
the growing pains and not wanting to let go of the "baby". However, 
unless this product is allowed to become an adult, it's gonna be 
hanging round in pool rooms til time for retirement!!!

All the Best
Dave