The API docs have the ability to let users “rate” the page and provide comments. I suggest doing this and letting Corona know that the information is not correct. The more people that use this system, the better the docs will get.
That is an excellent suggestion. I will do that right away and from now on when I detect a similar shortcoming. The issue goes well beyond the docs though. Simulator and even the samples that come with Corona SDK are not clear enough when it comes to platform differences… No response from CL as usual…
Hi Kerem,
As SegaBoy says, the best way to highlight issues in the documentation is by using the “Rate it” buttons in each document. Although we try to see and respond to most things in the forums, sometimes they slip by.
As for this message and the “no response from CL”, the time of your first post was 1:23 AM and the follow up at 10:21 AM, most of which is not “working time” in our time zone. As stated in the Forum Guidelines #5, we get to answering posts in a “reasonable” timeframe, which does not include the middle of the night. 
Regarding the documentation, I think we clarify platform differences in most cases. This one in particular was not done, but it appears that Tom has it on his list. I know you’d like the Simulator to work exactly like the device (and you noted this in your recent post about the system.getInfo() responses), but some of these things just aren’t the highest priority in light of so many other things that are being worked on.
Regards,
Brent
Brent, thanks for your response.
The doc issue was hilighted on April 17th in another thread and is still not fixed. Small issue perhaps but caused loss of time for me. The question is not how much time I lost over this one but how much time I will loose over other undocumented Gothas…
While we’re at it… I think the documentation overall is quite haphazard. Many parameters are not documented and you see them used in samples or mentioned in the forums. It is very hard to rely on the API docs without a degree of consistency.
Here’s a suggestion… Why not open up a blog response type capability on the API docs pages? This way when we see something not right or missing we can not only provide feedback to CL but leave it visible to others who come through the same direction. This would help CL and all. Once the doc is updated CL can delete the feedback which is no longer needed. Just an idea.
Regarding CL replies, I suppose I am frustrated due to many other posts / questions I have which has gone un-responded. I was not expecting a reply in the middle of the night and I for one always appreciate people like Rob who go out of their ways to respond over the weekend etc. Thanks for this reply as well.
My issue is not having a life line. As a pro license holder I feel there needs to be a more direct method of support other than the forum. The forum is great for what it is but attention is divided too thinly over all sorts of issues. Perhaps a CL Support line with a response SLA and an x number of calls or tickets per year for Pro and Enterprise approach might be what is needed here. Has this ever been considered?
Thanks once again for taking the time to response. Best regards,
Kerem
Another one… native.getFontNames() does not seem to be working on Android devices. If that is the case this is not mentioned at all on the API doc found at :
http://docs.coronalabs.com/api/library/native/getFontNames.html
I copy pasted the code example from the API doc page and ran it on 2 different Android devices. I can get a count for the fonts found on the system but not the font names. Is this a known constraint (aka Gotcha!) or a bug? I don’t know.
Thanks for your interest.
Hi Kerem,
Did you copy the exact sample from that page and compile it as an Android app? If so, did you remove the “Times” filter that’s only looking for fonts with “Times” as part of it? I’m not sure that exact font exists natively on Android…
Brent
My bad. Its working… I apologize for the false alarm.
I do know that using the “This kind of sucks because…” options at the bottom of the API pages do work. I’ve seen things changed/fixed because of feedback I’ve made.
About Kerem’s suggestion for responses to the API… when I look up stuff at php.net I look at the “official” stuff at the top and then if I need more info I scan down through the user-submitted things below. In many cases *that* is what helps me the most. Allowing something like that in the docs would be nice. No questions, just comments, samples, etc.
Jay
Yup. No questions, only comments & samples is very important guidance. Already there is a segmentation on blog posts vs forum posts etc when it comes to questions. Idea above can be implemented with ease I think.
Kerem and Jay, let me ponder this over the weekend. Frankly, a “blog” post type of thing in each document sends a shiver up my spine. It worked that way on the old site, and most often it devolved into a long, unruly conversation between a few people about their specific usage of a certain API, and how it should be done… heck, I contributed to some of those myself back in the day. I really don’t want to go back to that. 
That being said, a “comments” thing would probably be OK, but how does it get regulated? We can tell people to leave useful comments, and not ask questions, but unless every post is checked and approved, it becomes just like the old style.
I’d like to make it better for everybody, and more accurate, but I think the “feedback” buttons allow for that. Perhaps they’re just not visible enough or it’s not obvious what they’re for, so developers don’t often use them. I can definitely fix that…
Anyway, food for thought, keep your feedback coming in and I’ll present it to the team next week.
Brent
How about looking into volunteer guardian angels? You can set the blog type responses to API docs to be approval required and then assign some moderators to segments of API docs. I wouldn’t mind looking after few myself. Moderators job would be to weed out the questions and other stuff and point them politely to the forums. No extra burden to CL.
Thanks for hearing this out. Have a good weekend.
Is it actually a problem to have conversations below the API pages? I’ve often read through the comments there to get clarification, notice limitations for the API, alternate uses not mentioned in the API, etc. It’s not nearly as convenient to search through the forums for each API.
If it’s too ugly to clutter up the documentation with these, maybe they could be collapsed by default for each page, with a “read comments” button at the bottom?
Hi Brent,
Yes, comments at the bottom of the page: it did work that way on the old site indeed. Your apprehension of this feature surprises me: this was, bar none, the biggest source of wisdom for me while learning Corona. Basic everyday topics like creating and removing displayObjects, intermediate stuff like spawning, awkward little quirks, bugs and workarounds and even advanced stuff like metatables and OOP, I learned most of the good stuff that really makes the difference through the comments at the bottom.
Aditionally, even though you may not have liked this option, the current situation is definitely not a better one: far too often crucial information is missing, or one needs to compare API documentation, sample apps, forum posts, blog entries and example code to form full comprehension - sheesh! I do understand that CoronaLabs will never reach the full 100% completion of documentation - hell, I even prefer you guys working on features rather than docs strongly, but in that/this case, please give OTHER people (like motivated users) the chance to fill in the gaps in the place where you expect to see the info, which is the API documentation, and not the forums.
The change from comments below the API’s pre-dated me coming on board, so I was not privileged to all of the reasons. But I do know that today, our API documents are source controlled which lets us have Daily Build specific versions which was a real problem before the changes.
Policing posts won’t work very well from my experience.
Hi Rob,
I see your point. Hmmm… Tricky problem, but an interesting one to think about. No perfect solutions ready from my side, but here’s some of my thoughts…
-
Policing posts sounds like a waste of manpower, vs. development.
-
Daily Builds documentation should not adhere to the same standards as public builds - which ideally should be perfect and 100% complete, although in practice naturally this is impossible.
-
Each revision to an API could make earlier user comments obsolete, confusing or just plain wrong, which is problematic.
-
Building on point 2), could there be a way for docs to keep the user comments for the parts which didn’t change, and only be revised regarding updated parts of the API? These parts of the docs could then be rewritten by someone knowledgeable from Corona who could incorporate the relevant or helpful user comments.
-
Damn… Then again there’s content that needs to change because of the implementation of third parties, and not because CL changes something from your side… Tricky, tricky, tricky.
-
Could user comments be maintained or displayed with a disclaimer that the info is to be taken “as is”, with no guarantees whatsoever from CL?
Heh, in the end it looks like you guys aren’t doing so bad after all! I’m willing to accept the trade-off between speed of development and fluidity and flexibility on your part, and the quality of the docs which will inevitably suffer as a consequence (documenting a rigid and hardly ever evolving codebase is a lot easier, yep).
Although I will repeat that I think the docs and info are currently too scattered across (like I said before) the API docs, tutorials, blog posts, guides and more. There are links to these things from the API docs, I know, but it’s kind of hit and miss: sometimes there is a link where you would expect one, sometimes there isn’t.
Lastly, Rob, thank you and your colleagues (and David R) for being so accessible to us - it’s been said before but there’s no harm in mentioning this again once in a while. It’s nice to see there’s no vacuum after people like Carlos and Peach moving on to other endeavours.
I mentioned the php.net site before, and here’s a look at their submission page:
http://us2.php.net/manual/add-note.php
And right at the top of the form they tell you that questions, etc., will be deleted. So “policing” in a situation like this, can be quick and painless. I don’t know their exact process, but since they say it will appear after about an hour, I imagine it goes into some kind of “holding tank” where admins have a chance to kick it to the curb if it doesn’t fit.
You guys have Ambassadors who have at least some tech savvy. And you have a number of other people who hang around here who are passionate about Corona SDK. I don’t think finding people to vet incoming API comments would be a problem.
Process:
- User adds a comment which is added to a queue.
- For a 1-hour (or whatever) period the comment is viewable by API Police.
- If it’s still around at the end of an hour, it gets added to the bottom of the API page.
It may not be something you guys could implement tomorrow, but it’s also not a huge infrastructure thing.
Jay
PS - Allow API Police more than just Yes/No for a submitted comment. Maybe a “Not Sure” that would put a hold on the comment until another API cop gave it a thumbs up or down. Kind of a triage thing.
Hi guys,
This is a valuable exchange of ideas. Until we decide what changes can (and should be) realistically made, I wish more developers (all of you!) would use those “rate” buttons at the bottom. There are dozens (actually hundreds) of docs, and with your help we can make them better for all. If you tell us what’s missing, incomplete, somewhat unclear, or what you don’t fully understand about a particular API, we can discuss (one on one via e-mail, if it helps) how to make them better.
Take care,
Brent
Brent,
thanks for listening and being open to these ideas. It is most appreciated. I will definitely be using the rate this … button more in the meanwhile now that I know what its for!
Keep well.
Okay - I’ll try to make an effort to use the “rate”-button more, and will conversate if I find something lacking!