Clean up your documentation!

Solar2D General Questions/Discussion
#21

There are a lot of good things about the documentation now and getting updates with each daily build is an important feature.

But at the end of the day, its about the content of the documentation and does it help you write your code better/faster/stronger and able to leap tall buildings…

For many of the API calls, the docs are good. I won’t say any of them are great. However some are simply lacking to useless. For example, try finding out anything on what is in the event table for widget.tableView events. I’ve already had my rant on this and I know the folks at Corona Labs are working.

The problem with the voting at the bottom is time. It takes you to a form where you have to check why you don’t like it, type in some text and enter you’re email field. I know the form is with an external vendor, but surely there is a way to populate the email address so we don’t have to type it in.

For most programmers, we hit the documentation either when we need to quickly look something up or when we get stuck and are looking for a solution. In the first case, I don’t want to spend time, breaking my train of thought. When programmers are interrupted, it takes nearly 30 minutes to get back going again so hitting the like/dislike button when there are additional forms to fill out isn’t going to be high on anyone’s priority. When we are stuck, then we might have more time to complain about this.

I will strive to do a better job of flagging bad documents if that’s the best way to let Corona Labs know where there is a problem.

Each API call should have every method, attribute and parameter listed with examples. For every event that fires off, I’d love to know what the event table contains. It may be a lot to ask, but it’s something we need.
[import]uid: 19626 topic_id: 30689 reply_id: 123818[/import]

#22

Hi @jacques1,

Certainly you have a right to voice your opinion as a paying customer. If you’re not finding the info you need to code efficiently or effectively, then you should express it.

I’m just curious as to how the current docs are frustrating you so horribly now, versus how they were in the “past”. I’ve been using Corona for about 2 years, and I don’t remember the past documentation being much easier to navigate, find info, etc. The main difference is that the “comments” section is now gone… you probably recall when there was a forum-like thread feature for every API where users could comment and suggest changes, usage tips, etc. about a particular API. While this was helpful to a certain degree, it was also messy and disorganized. Most often, we’d need to shuffle down through 10-20 posts to locate some comment by a developer who had a tip or suggestion about using that API. Personally, I didn’t find that any easier to use. :slight_smile:

Anyway, I’ll ask again (and I’m not being condescending at all, this is 100% sincere): What would make the API documentation easier for YOU to use? If you’re this frustrated, I’m sure many other devs are too, but they’re just not saying it. What would help you, as a “non-programmer”, locate and find the API info/usage easier to use and more clear? You say it looks like a tech engineer’s list… so how do you feel it could be improved? You obviously have a strong opinion on this, so it would be useful to hear your thoughts about how to fix it. That’s why I urged people to comment in this thread, and so far, we’ve heard many ideas. Corona Labs needs your ideas too. :wink:

Sincerely,
Brent Sorrentino [import]uid: 9747 topic_id: 30689 reply_id: 123832[/import]

#23

Hi everyone - please keep any ideas coming. We are listening.

As mentioned above, each daily build does come with docs that should include the latest changes.

We are definitely aware that our docs are lacking still and we are working to fix it.

Also - we definitely pay attention to, and do fixes based on, any comments via the “I love it/like it/hate it” buttons. So please do comment away.

Thanks,

David
[import]uid: 10668 topic_id: 30689 reply_id: 123766[/import]

#24

Wiki would be great. This way we could add things to them and you (Corona staff) could have control as well. You could allow only registered users to edit the entries. [import]uid: 160496 topic_id: 30689 reply_id: 123772[/import]

#25

I have no idea if it’s just me or is it really impossible to find any proper docs on corona’s site nowadays. I remember a long time back the api/resource pages were very helpful, now they look more like some tech engineer’s list that’s completely unhelpful & useless to us developers. Secondly, after downloading a new build’s api docs I’m surprised that items marked as new to the build aren’t even in the docs, well not that i can find anyway due to the horrible user flow to find things.
For example i just read about the native.showPopup() for ‘rateapp’. Ok seems interesting, so i downloaded the latest build’s docs… Hmm, surprise surprise, no mention about it… perhaps there’s a secret tech way of actually find information these days…? I’d be interested in knowing how this process to find relevant information works because using corona sdk is becoming increasing frustrating, annoying and apparently a waste of time. [import]uid: 66228 topic_id: 30689 reply_id: 123788[/import]

#26

The post did say it will be in *next* build… [import]uid: 160496 topic_id: 30689 reply_id: 123799[/import]

#27

that was build .904, now its already .906, anyhoo that’s not the point, just totally frustrated with the pathetic lack of properly organised documentation that is now becoming the norm for corona. Corona is a great tool but even me as a non-programmer am now tempted to switch to xcode so i can avoid all the BS constant changes or lack of due to their focus ‘elsewhere’… and before it’s said “no one stopping me”, well the usd$199 i paid for my yearly renew is at least a good reason for me to have the right to complain and attempt to stick with corona for another year :wink: [import]uid: 66228 topic_id: 30689 reply_id: 123801[/import]

#28

There are a lot of good things about the documentation now and getting updates with each daily build is an important feature.

But at the end of the day, its about the content of the documentation and does it help you write your code better/faster/stronger and able to leap tall buildings…

For many of the API calls, the docs are good. I won’t say any of them are great. However some are simply lacking to useless. For example, try finding out anything on what is in the event table for widget.tableView events. I’ve already had my rant on this and I know the folks at Corona Labs are working.

The problem with the voting at the bottom is time. It takes you to a form where you have to check why you don’t like it, type in some text and enter you’re email field. I know the form is with an external vendor, but surely there is a way to populate the email address so we don’t have to type it in.

For most programmers, we hit the documentation either when we need to quickly look something up or when we get stuck and are looking for a solution. In the first case, I don’t want to spend time, breaking my train of thought. When programmers are interrupted, it takes nearly 30 minutes to get back going again so hitting the like/dislike button when there are additional forms to fill out isn’t going to be high on anyone’s priority. When we are stuck, then we might have more time to complain about this.

I will strive to do a better job of flagging bad documents if that’s the best way to let Corona Labs know where there is a problem.

Each API call should have every method, attribute and parameter listed with examples. For every event that fires off, I’d love to know what the event table contains. It may be a lot to ask, but it’s something we need.
[import]uid: 19626 topic_id: 30689 reply_id: 123818[/import]

#29

Hi @jacques1,

Certainly you have a right to voice your opinion as a paying customer. If you’re not finding the info you need to code efficiently or effectively, then you should express it.

I’m just curious as to how the current docs are frustrating you so horribly now, versus how they were in the “past”. I’ve been using Corona for about 2 years, and I don’t remember the past documentation being much easier to navigate, find info, etc. The main difference is that the “comments” section is now gone… you probably recall when there was a forum-like thread feature for every API where users could comment and suggest changes, usage tips, etc. about a particular API. While this was helpful to a certain degree, it was also messy and disorganized. Most often, we’d need to shuffle down through 10-20 posts to locate some comment by a developer who had a tip or suggestion about using that API. Personally, I didn’t find that any easier to use. :slight_smile:

Anyway, I’ll ask again (and I’m not being condescending at all, this is 100% sincere): What would make the API documentation easier for YOU to use? If you’re this frustrated, I’m sure many other devs are too, but they’re just not saying it. What would help you, as a “non-programmer”, locate and find the API info/usage easier to use and more clear? You say it looks like a tech engineer’s list… so how do you feel it could be improved? You obviously have a strong opinion on this, so it would be useful to hear your thoughts about how to fix it. That’s why I urged people to comment in this thread, and so far, we’ve heard many ideas. Corona Labs needs your ideas too. :wink:

Sincerely,
Brent Sorrentino [import]uid: 9747 topic_id: 30689 reply_id: 123832[/import]