RB Language Reference

Am I the only one that think the RB Language Reference is less than useful?  Honestly, it seems about the only time I check it now is when the auto complete messes up (usually by not giving me any choices) and I want to make sure I’m not wrong on what I thought AC should show.

I’ve said it before and I’ll say it again, I think having the Language Reference online with user added comments is better solution.  In my ideal world, the local Language Reference gets the comments from the web IF I want them (and I do in most cases).  It’s a brave new world and it’s time to embrace the web (of course this means we need a new/reliable web browser control but again, that’s a different topic – see here, here, and here).

You know it’s bad when you think OPEN SOURCE documentation is better.  See Java, php, MySQL documentation for examples.

Am I wrong about this?  Or am I not looking at it from a complete newbies perspective?  Maybe the LR is good for beginners and not for experienced users because I’ve heard from various sources that new people really like the language reference.  However, I also see an awful lot of questions being answered on the forums that might have been eliminated if a simple comment or two was added in the Language Reference.

Thoughts?

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.

REALbasic Wiki Thoughts

There has been considerable talk on the REALbasic forums (link) about the possibilities of an RB Wiki. I think it has loads of possibilities but people have to look at the drawbacks and from REAL Software’s perspective. First, a little history.

There was a wiki, appropriately named ‘RBwiki’ a while back.  I believe it was created just before REAL World 2006 and started with much fanfare and a lot of promises by volunteers to keep it up-to-date.  A large contributor of the wiki was Thomas Templeton who used it to distribute the RBProjectTool that allowed people to use source code and version control systems with RB (before the rbvcp format was introduced).  It was a tool that allowed RB users to read and write between RB binary source code files and text files for use with Subversion and CVS and the like.  REAL World 2006 was where REAL Software announced the version control format and Thomas and the REAL engineers sat down and compared notes.  I think it safe to say that todays rbvcp format is a direct result of the collaboration.  That also meant that the interest in the RBProjectTool died rather quickly.  In about a year, the wiki was dead – no one wanted to keep it up to date.

So why have an RB Wiki?  The answer is simple:  the language reference is not very useful.  In some cases, the documentation is lacking important information and sometimes missing or woefully out of date.  I know that a lot of people find the example code not useful and I admit that I feel the same way and have a tendency to avoid the language reference.  I think the pdf files that can be directly opened from REALbasic are more useful.

So while an RB Wiki sounds really cool it’s not integrated into REALbasic.  I think the integration is key because when I want to find information quickly I don’t want to switch to a browser no matter how quickly I can get to things.  I want the information NOW.

As much as I hate their particular implementation of their help, I have to give it to Microsoft in attempting to integrate online resources into their help system.  I’m currently using Microsoft SQL Server 2005 for a big project and use their help system a lot.  They essentially have three sources of information:  the local help files, MSDN online and a search of appropriate newsgroups.  It’s more or less built-in.  Forget about the fact that it never seems to find any local information – it eliminates the step of having to go to the browser and find the newgroup to search.

If the language reference used the local and online approach (and I want to turn off the online search if I want) it would be light years ahead of what it is now.  Of course, I want the ability to add comments but only after they’re approved by someone on the RS Staff.  Look, we’re not talking about elimination of free speech, just an elimination of the useless chaff that invade the NUG list and forums every three months or so.  I want to see the local information in addition to comments that other developers may have added.  In my ideal world, I’d also love to see relevant NUG and forum listings as well but not as often.

I think there are ample examples of truly excellent language references that one could copy from the web:
•    PostgreSQL documentation.  Excellent use of user comments.  I linked to an installation requirement, but I think it illustrates what the community can do with comments.
•    php documentation.  This site illustrates the concept even better, I think.

This all sounds great, but in my opinion, anything that’s not sanctioned and policed by REAL Software won’t last.  From their perspective, a wiki doesn’t work well – they don’t have enough control over it and the comments could get out of control really fast.  Think about how much trouble Wikipedia gets into when an entry is wrong or been edited by the wrong people.  The wiki folks won’t be able to use the text from the Language Reference without REAL Software’s permission due to copyright concerns and this is a big deal because it’s the base documentation and there’s a lot of it.  Starting from scratch isn’t very fun.

So what can you do as an RB Developer?  Sign on to the various feedback requests that deal with the Language Reference:
▪    http://support.realsoftware.com/feedback/viewreport.php?reportid=ocjotmpv – Open Source the Language Reference
▪    http://support.realsoftware.com/feedback/viewreport.php?reportid=hosltpxz – Allow the IDE to download updates to the Language Reference without a new version.
▪    http://support.realsoftware.com/feedback/viewreport.php?reportid=cgkaheyh – Allow annotations to the Language Reference
There are probably a few others that would be worthy of consideration as well but these are a start.

Feel free to give me your thoughts.