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.