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?

7 thoughts on “RB Language Reference

  1. Personally, I like the LR…..personally, the examples and some information pertaining to certain classes and subjects leaves alot to be desired.

  2. I am an RB developer, with several bespoke database apps in use by my clients, but I also do Mac consultancy, installations, support, and training. The LR is vital for me, as I don’t use RB all the time, so I just forget stuff from time-to-time. And when I am looking for something, I often come across something else I didn’t know, which can be good and makes life easier for future work. Also, I travel to some client sites by train, and sometimes use the journey time to make changes to my RB apps using my laptop. Having the LR on-line would be useless. I prefer the LR to a PDF of the same information. I think the on-line MySQL language reference is good but sometimes you get too much information. The RB LR is about right, but I would like to see more examples.

  3. I’ve always found the lack of useful information to be disconcerting. Then again, my jobs always require me to have a lot of technical background information, so my opinions may not be applicable here. But a great example of what I consider to be unacceptable would be ComboBox.Text — when I look in my LR, the entire entry says “Gets or sets the text of the current item.”

    1) What’s the current item? This, to me, implies that if I select list index #3, then do .Text = “blah”, it will change list index #3’s text.

    2) What happens if I set the text? Do any events fire?

    3) What happens if no item is selected in the list?

    There are other questions as well, but you get the idea.

    This isn’t what I’d consider documentation so much as “explaining the obvious.”

  4. Eric :

    Having the LR on-line would be useless. I prefer the LR to a PDF of the same information. I think the on-line MySQL language reference is good but sometimes you get too much information

    In my ideal world the Language Reference would remain as part of the package so you could use it offline. But the user comments would be retrieved from the web when the user wants them.

    As long as I’m dreaming, I want to be able add comments to my local Language Reference and be able to submit it to the web from there. I would also like a separate updating mechanism so the language reference can get updated any time rather than the silly 90 day interval we get now.

  5. I think you’re onto something here… I’d be wary about having just ANYONE edit or put comments. Sure you could do a reddit style voting but as can be witnessed on the listserv sometimes the answer gets better as you read the thread. The initial response isn’t always the best response. Of course then you have to read a long discourse which includes a lot of non sequiturs. I’d like to see it have a “membership” kind of system that promotes responses from the more thoughtful members of the community. Or at the very least be moderated by them. Just opening up it up sounds like it has the potential to make a bad situation even worse.

    I’m with you though… Having bad docs is a huge source of frustration. Back when Aaron used to blog I was constantly amazed at some of the ideas and concepts that eluded me. Some people have a better gift of conveying concepts than others. It’d be nice if RS had such a person righting their docs.

  6. Way way back I think around 2004-5 I tried to spawn interest in everyone compiling an RB Cookbook of sorts like they did with Python and other languages.

    Sounded like a great idea but it never materialized. They actually started something similar back when in the heyday of realgurus.

  7. Tom Russell :

    Way way back I think around 2004-5 I tried to spawn interest in everyone compiling an RB Cookbook of sorts like they did with Python and other languages.

    Sounded like a great idea but it never materialized. They actually started something similar back when in the heyday of realgurus.

    I’m not familiar with the cookbook idea but the ARBP source code repository is a place to put those snippets of code so that they’re in one spot. At one point I was a big fan of RBGarage (and still visit regularly) but it has the disadvantage of being linked to the original site instead of having the code. The site goes down and that information is lost forever unless someone retained a copy. Examples abound of people and sites being lost.

    As with all things, unless there is a core group of people committed to something happening, it’s just not going to happen. A number of people have tried an RB wiki and have failed. Perhaps until RS officially backs something and/or gives permission to use their existing documentation I’m not sure if anything will ever get off the ground. In any event, ARBP is trying to change some of that and if someone is willing to spearhead an effort I think we’d be willing to provide hosting and other types of support.

Comments are closed.