Clean up your documentation!

Solar2D General Questions/Discussion
#1

I would really love it if corona spent more time cleaning up their documentation then spending time developing redundant things like level editors and god knows what else!

It is truly frustrating to weave in and out of a gazzilion pages of api resources to find useful documentation, and when it is finally discovered it turns out its already obsolete because of a new build! If it’s not obsolete then it has several options in how to code it and what api’s you can or can’t still use…!

For example the sprite API, it was updated sometime ago but half the documention still refers to the old api way of doing things and i don’t even see documention on the new sprite api unless u can finally find your way to the blog!!!

PLEASE, do us all a favour and spend some time cleaning up your api documents! It’s hard enough for us to keep changing all our code because of new changes in builds. Needing to search high and low for relevant documentation and then not even knowing if its still relevant and just plain annoying!

You have a great platform, don’t destroy it with BAD documentation. [import]uid: 66228 topic_id: 30689 reply_id: 330689[/import]

#2

This might be a good thread to begin a flow of ideas on HOW to improve the documentation. Do you (or others) have any specific ideas about the docs system which you’d like to see? How do you envision it working to accommodate those developers using the latest Daily Build AND those who are several builds back?

It’s true that some material is outdated or, in some cases, totally depreciated. But taking that info out isn’t always the best solution. Until an API is officially unsupported, it needs to remain in the documentation for those devs who don’t constantly update their apps to the “bleeding edge”.

So everybody… Ideas? Grand visions on the documentation system you want to see and want to use? Let’s brainstorm ideas and hopefully some of it can happen.

Brent Sorrentino [import]uid: 9747 topic_id: 30689 reply_id: 122972[/import]

#3

maybe a easy search engine in the forum… Or am i not looking good enough?

Then a forum where we put in all sample codes and extended feature plus the normal documentation.
then every one can search there stuff [import]uid: 164820 topic_id: 30689 reply_id: 122984[/import]

#4

How about a kind of wiki system where anyone (maybe limit to indie/pro subscribers) can add/amend/recommend changes to the documents? [import]uid: 62706 topic_id: 30689 reply_id: 122986[/import]

#5

I believe that API doc that we can now download with the daily build is meant to include updated documentation to accommodate for the changes made to the SDK (meaning, as opposed to the online version that works with the latest stable/public release.)

Anyhow, I think Love it button, Like it, but… button and Hate it button that appear at the bottom of the each API screen is a great idea. If all of us make the effort to submit comments (I usually pick “Like it, but…”) regarding any problems that we find in these pages every time we come across one, the documentation will become much more solid and less prone to issues over time. Or at least it will help getting Corona Labs team to focus on specific pages (or compile list of specific pages) that need improvement.

Naomi [import]uid: 67217 topic_id: 30689 reply_id: 123014[/import]

#6

Personally, I like the “Wikipedia” idea CraftyDeano… and yes, limited to paying developers (Indie or Pro). This way, certain additions or “tips and tricks” could be added by developers, enhancing ideas about how to use the API. This is somewhat how the old documentation system worked, where we could all make comments in a forum-type method… but that usually resulted in a mess of comments and responses, and it was equally difficult to find anything in those comments. A “wiki” system would keep things clean and accurate.

So, +1 on this idea.

Brent
[import]uid: 9747 topic_id: 30689 reply_id: 123071[/import]

#7

Hey guys - will make sure this thread gets looked at by the team, any input on docs, site, etc - anything you feel we can improve - is always welcome :slight_smile: [import]uid: 52491 topic_id: 30689 reply_id: 123081[/import]

#8

I like docs that are in databases – then you can pull against that to create web pages, PDF files, in-app help, etc. Allowing a read-only API against that database could help 3rd-party tool developers. If you put docs in a web page you’re really limiting what can be done with the info.

Also, allow people to tag items – all items. API, reference docs, blog posts, shared code, forums posts, etc. Then doing a tag-based search could pull up all the relevant info we’re looking for.

Jay [import]uid: 9440 topic_id: 30689 reply_id: 123082[/import]

#9

This might be a good thread to begin a flow of ideas on HOW to improve the documentation. Do you (or others) have any specific ideas about the docs system which you’d like to see? How do you envision it working to accommodate those developers using the latest Daily Build AND those who are several builds back?

It’s true that some material is outdated or, in some cases, totally depreciated. But taking that info out isn’t always the best solution. Until an API is officially unsupported, it needs to remain in the documentation for those devs who don’t constantly update their apps to the “bleeding edge”.

So everybody… Ideas? Grand visions on the documentation system you want to see and want to use? Let’s brainstorm ideas and hopefully some of it can happen.

Brent Sorrentino [import]uid: 9747 topic_id: 30689 reply_id: 122972[/import]

#10

maybe a easy search engine in the forum… Or am i not looking good enough?

Then a forum where we put in all sample codes and extended feature plus the normal documentation.
then every one can search there stuff [import]uid: 164820 topic_id: 30689 reply_id: 122984[/import]

#11

How about a kind of wiki system where anyone (maybe limit to indie/pro subscribers) can add/amend/recommend changes to the documents? [import]uid: 62706 topic_id: 30689 reply_id: 122986[/import]

#12

I believe that API doc that we can now download with the daily build is meant to include updated documentation to accommodate for the changes made to the SDK (meaning, as opposed to the online version that works with the latest stable/public release.)

Anyhow, I think Love it button, Like it, but… button and Hate it button that appear at the bottom of the each API screen is a great idea. If all of us make the effort to submit comments (I usually pick “Like it, but…”) regarding any problems that we find in these pages every time we come across one, the documentation will become much more solid and less prone to issues over time. Or at least it will help getting Corona Labs team to focus on specific pages (or compile list of specific pages) that need improvement.

Naomi [import]uid: 67217 topic_id: 30689 reply_id: 123014[/import]

#13

Personally, I like the “Wikipedia” idea CraftyDeano… and yes, limited to paying developers (Indie or Pro). This way, certain additions or “tips and tricks” could be added by developers, enhancing ideas about how to use the API. This is somewhat how the old documentation system worked, where we could all make comments in a forum-type method… but that usually resulted in a mess of comments and responses, and it was equally difficult to find anything in those comments. A “wiki” system would keep things clean and accurate.

So, +1 on this idea.

Brent
[import]uid: 9747 topic_id: 30689 reply_id: 123071[/import]

#14

Hey guys - will make sure this thread gets looked at by the team, any input on docs, site, etc - anything you feel we can improve - is always welcome :slight_smile: [import]uid: 52491 topic_id: 30689 reply_id: 123081[/import]

#15

I like docs that are in databases – then you can pull against that to create web pages, PDF files, in-app help, etc. Allowing a read-only API against that database could help 3rd-party tool developers. If you put docs in a web page you’re really limiting what can be done with the info.

Also, allow people to tag items – all items. API, reference docs, blog posts, shared code, forums posts, etc. Then doing a tag-based search could pull up all the relevant info we’re looking for.

Jay [import]uid: 9440 topic_id: 30689 reply_id: 123082[/import]

#16

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]

#17

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]

#18

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]

#19

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

#20

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]