Enhancing the Language Reference

For the past couple of weeks I’ve been talking about things I’d like to see in REALbasic and what, I think we, as users, can do for REALbasic.  The comments have been great – I appreciate all the time and effort all of you have put into them.  I think I’ve settled upon one thing that I’d like to see changed in REALbasic.

The Language Reference in RB is, depending upon who you ask, is either barely adequate or downright horrible.  I tend to leans towards the former because I think it’s lacking depth to be very useful.  For every object, property, method and event there’s information needed but not in the LR.  Sometimes this includes bugs but more often than not, just clarification on what’s changed.

For example, in RB 2007 R5 using “Dim as New Recordset” generates a compiler error.  It’s easy to fix and the release notes showed the change.  However, it would have been nice for the LR to have a note saying that the functionality was changed for that version of RB.  And I don’t blame RS for not having that in the LR either.  With all the things on their plate, this is, I’m sure, not a very high priority and, after all, they DID document it in the release notes.

I’d like to see user contributions to the Language Reference.  Note that this is somewhat different than a regular Wiki in that the users wouldn’t be able to add completely new topics, just add comments to existing topics.

Ideally, I’d like to have the option to turn the user comments on and off in the IDE.  If turned on, the LR would open up as it normally does and user comments would be displayed below the official entries.  Take a look at this documentation page for php.  I think this is a wonderful use of user comments to clarify what the object/property/method/event does.  This would make the LR rock in my opinion.  There are other examples around the web – if you have additional examples, please add them in the comments section.

So why is this different that the RB Wiki (hosted by Charles Y.) that is here now?  For one, this would have to be an official RB add-on.  They’d have to add the hooks into the IDE and the existing LR documentation.  They have also been unwilling to allow the use of the existing LR documentation (even though they’d keep the copyright) in past Wiki efforts.  This limits the options available.

To prevent spam and inappropriate comments, the contributions have to be moderated by someone.  All user comments would have to be approved by the moderator before being posted.  No comment is added without it being approved by the moderator – no matter who the user is.  This eliminates crap and will hopefully assuage RS of the crap and embarrassing entries that often happens on other wiki’s.  I hereby, put my money where my mouth is, and volunteer to be a moderator.

The Terms of Service would make it clear that RS retains the copyright and future use of all user contributions.  Most comments won’t be that useful, but I’m sure there will be a few, but those that are useful can be rolled into the official documentation.  The TOS would make clear that RS reserves the right to clear the comments at any time for any reason.  I see this happening when the official documenter gets around to any specific object and rolls comments into the documentation.

I’m sure there are things that I’ve forgot to mention but I think that’s the basics of it.  So how do we sell this to RS?  It’s work for them and they’ve not been especially enthusiastic about things like this in the past.  How do we propose a system so that it’s a win for RS and win for us users because I think this could be a nice collaboration between RS and the users.