Appcelerator, are you intentionally leaving API documentation incomplete?
Love what you guys are doing with this platform! And I know you need to sell support packages to make the open source business model work. But are you intentionally leaving the API documentation incomplete?
Simple example from http://developer.appcelerator.com/apidoc/mobile/latest/Titanium.Map.Annotation-object.html:
It states that Titanium.Map.createAnnotation has an image property that replaces the default pin image and only works on the iPhone. Bummer. No pin images for Android.
By some fluke as I was researching an unrelated issue, I noticed someone's code in a Q&A post that had a pinImage property. Low and behold, I've got pin images on Android!
What about Titanium.Geolocation.reverseGeocoder? How could that one have gotten left out?
A problem I had tonight: MapView events don't seem to be firing. Hours wasted until I read this Q&A, which informs that loading—and presumably complete and touchend, the ones giving me trouble—don't work on Android. Would have been nice to know.
Can't recall the other instances off the top of my head, but I've spotted other omissions with the API docs when comparing to KitchenSink code and Q&A posts.
On that note, it's rough that there's all this great looking sample code in KitchenSink, yet judging by the number of questions, many people can't get it to run. I gave up myself.
The situation with Titanium and the startup I work for: I thought Titanium looked sweet and wanted to prototype an app to see if it can really cut it. The moment that's a yes, I'm moving out of a prototype mindset, thinking production code and I'm on a premium support plan.
If you guys could make this stuff a little easier I might already be paying.
Here's a simple idea that would be cool for the premium docs: Screenshots of all the UI components.
Thanks dudes. Keep up the good work.
7 Answers
-
Accepted Answer
The API docs aren't intentionally incomplete. We're working on revamping them right now and increasing the coverage - we know there are gaps. It's kind of tough because since the API isn't actually implemented in JavaScript anywhere, we can't really use standard documentation tools. We have to manually generate docs from documentation files that we write ourselves, so sometimes properties and functions don't get written up. Finding Kitchen Sink examples that aren't written up is frustrating, so I'm going to make sure we go through that example to make sure we cover all of those items.
Most of the Kitchen Sink issues have to do with issues downloading the source and importing directly - if you can create a new project, copying the contents of the Kitchen Sink Resources directory into the new project's Resources should get you going.
-
Was thinking of suggesting a wiki, then this topic appeared!
No harm in setting one up alongside the existing doc to see how it goes…
-
Until the guys at Appcelerator find the time to improve their own documentation, I'm going to start a community wiki. If there are folks that like to help me with it, you can contact me at titanium [at] doney [dot] nl.
The wiki can be found here :) Feel free to improve it and create new pages!
http://www.doney.nl/titanium/ -
Precisely! I've already suggested it; why no wiki ? This way people can help each other by extending the documentation. :-)
-
What Doney said. A Wiki could be so brilliant!
-
A community wiki would be a plus for sure !
-
Just registered a domain now and will bring a wiki up and maybe more soon…help would be appreciated…you can contact me on twitter @jipiboily or by mail jipiboily [at] gmail [dot] com
Thanks!
Edit : it'll be titaniumcommunity.com…I'll work on this friday probably.