Constant 'Nonsense' about RR documentation

[Eric Chatonet]

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?

> 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 :-)

> 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 :-)

Best Regards from Paris,

Eric Chatonet.
----------------------------------------------------------------
So Smart Software

For institutions, companies and associations
Built-to-order applications: management, multimedia, internet, etc.
Windows, Mac OS and Linux... With the French touch

Free plugins and tutorials on my website
----------------------------------------------------------------
Web site        http://www.sosmartsoftware.com/
Email        eric.chatonet at sosmartsoftware.com/
Phone        33 (0)1 43 31 77 62
Mobile        33 (0)6 20 74 50 86
----------------------------------------------------------------