03-10-2010 06:51 PM - edited 03-10-2010 06:52 PM
Hey gents. This is not one of my numerous questions, but a request to the BB team:
I like most of you, use the API reference site constantly. However, learning BB Java has been made harder because each class/method does not have code samples, and detailed explanation of how to use it.
Also, to learn something new, you need a clever advanced search for the whole API reference, which searches the text as well.
My second BB app will take a couple months, which is good, but my first took 10 when it should have been 6-7. Am I nuts or is this an important resource improvement for everyone on this group- anyone?
03-10-2010 07:04 PM
Generally, every method does not need a code sample. It is true that API documentation for the behaviour of each method needs to be improved in some places, but generally, the API documentation does it's job appropriately.
03-10-2010 08:52 PM - edited 03-10-2010 08:54 PM
I agree with Justin that RIM could do a much better job with documentation but I think the issue declines in importance for the more accomplished developers since they amassed knowledge of the API structure and its implementation as they did several projects.
Also, they're more likely to have a support network built up amongst their peers and they are better at knowing how and where to look for online answers.
A well written programmer's reference manual -- such as the one available for VB -- is something I use still today even though I've been programming in that language since VB version 3. If you can do a quick search on the virtual PRM or even look through the thick book (like we used to do in the mid 90s,) you tend to do it rather than continue to chase your tail with a piece of code that's causing problems.
Having a problem with a method and looking at examples of how it's normally implemented will generally get you back on track much more quickly then hoping to eventually figure it out or trying to find the answer on the forum where you may or may not construct the search term correctly.
But here's the thing: RIM simply doesn't dedicate the resources to do as good a job with documentation.
Even though they own 20% of the SmartPhone market (2009 numbers), their support of independent developers is apparently not a high priority to the corporation. We're blessed to have Mark and occasionally another RIM resource, but a person or two can't possibly take the place of decent documentation.
If the documentation were better, people like me who are still novices would be much better off.
But, if my experiences in the other language are any guide, so would the journeymen and experts.
03-11-2010 04:52 AM
I can't compare what RIM have supplied with other languages, all I can say is what they supply now, especially with the OS 5.0 API documentation, is significantly better than what it was when I started.
And I expect it to get better. I spoke to one of the people responsible for documentation at DevCon and he stated his goal, especially with the newer APIs, was to do exactly what you have requested, i.e. provide a simple standalone example of the use of any of the methods and classes in the JavaDoc.
But that in itself is not, in my opinion, enough. My belief is that a significant number of the problems that are addressed on this forum are architectural - in other words how things work, rather than documentation issues. As an example, the way you need to use the Event Thread to manage UI interaction can not be explained in a simple example in the API documentation.
So there is still a need for a 'manual' and RIM do provide the various developer guides that describe issues like the Event Thread and these manuals are peppered with samples. And there are many samples and additional documentation in other places like the KB.
In summary, I would not expect to get all the answers from the API documentation. And I don't think the answer is one reference Manual.
I agree that experienced developers are better at knowing how and where to look for online answers. So I believe the answer is an easier to use consolidated Developer web site. Given the way this site has developed since I started, I don't think it is fair to say that RIM is not committed to assisting developers. But at the moment there are a variety of places to look and the searching can be problematic. However I expect further improvements, hopefully including a 'wiki' where we can contribute samples and debate these. Would that be another step in the right direction?
03-11-2010 05:47 AM
Does anyone else think that somebody should start a WikiBlackBerryCode? A site with each commonly used class/method and code samples that anyone could add to (and anyone could debunk if they weren't up to scratch).
It would be a way for people who have learned like myself, of putting something back.
Something like this may have already been done, but we need one which is very visible, patronised by most of the developer community and well designed. I suppose it's not strictly professional for anyone to contribute to it, so maybe RIM wouldn't back it.
Maybe there's a better way than a Wiki?
03-11-2010 06:47 AM
"Does anyone else think that somebody should start a WikiBlackBerryCode?"
Absolutely. There have been other Threads that have suggested the same thing. I have been hassling RIM for this because I think it needs to be supported, and there are some indications that it might be happening. So I would suggest you don't start one just now, give RIM a bit more time....