I also found a nice read about “API doc” examples:
1 Like
Thanks for sharing!
Really? What exactly were you searching for? I see all essential information right at the top. But there is a lot more information below it, if I need or want more. Actually, when working with PHP I’m more often than not even ignoring the main documentation and jump right to the comments. As the documentation is mostly trivial information anyway, which I very rarely need.
E.g. for a problem, which one comment is describing/explaining and has a solution.
And this is exactly the problem. The solution for a problem might be hidden in one of hundreds of comments. You can only get to the solution, by digging through all the comments. It’s neither easy to the eyes nor very comfortable.
You are exactly describing a second problem here. If the official documentation would be sophisticated and also feature non-trivial things, there would be no need to dig through comments.
Ok, finally
The Cocos team can not provide full high quality documentation because they do not have the resources and time.
They are asking the community to help them with this. But send a request to you is not too convenient, not as convenient as correct wiki or write a comment.
So,
-
The team can continue to write documentation alone, because users do not have enough time or too lazy to help in such conditions. In this case, we can wait for new good documentation for years. And the team will receive complaints again and again.
-
Or you can try to motivate users.
-
Or the team finds a way to ease the writing of content to users. We get noideal documentation, but it is better than nothing. Or better than to wait for ideal documentation for years.
I said about the fact that sometimes it may not be convenient to look for a specific case among the hundreds of comments, because I imagined how will look comments to chapter “Sprite”, and I will be uncomfortable to look for “how to use inheritance and did not lose the opportunity to use create()”. But it seems that in this situation it is better to search among hundreds of comments than not found at all.
Sorry, your answer did not give me any understanding of what exactly you are going to improve.
And thank you for clarifying your position about the wiki.
No, this is not the case, pull requests are the best way for us. The Wiki is more work to maintain in my opinion.
It is not too convenient for users.
Here is an example
I now know how to make a comfortable inheritance to the sprite, but to add this information in the guide, I need to learn how to use the special markup (I do not remember the name technology that you are using for the guide) and learn how to use github.
p.s. I will not do it for a few small pieces of information that might not wanted. So I have a lot of hand-written pieces, some very large, half of them I have lost. And it is more difficult to force myself to edit and send as much information.
I guess it depends upon the users. I think a lot of them are familiar with GitHub.
It boils down to the fact we just can’t make everyone happy. Our goal then has to be making as many people as happy as we can.
I understand you.
The only question that I have is
How many users will begin to actively improve the documentation if it becomes very easy? You can create a survey about it if you are interested as well. Or not.
Thank you for clarifying your position.
I don’t know how many will. We have folks that do it now in it’s current workflow. Would this number go up. I don’t know. I don’t see us making any changes at this time.
Our workflow is GitHub. We accept PR’s, in whole or in part for our products that are open-sourced.
If someone really wants to contribute doc changes, but doesn’t want to learn GitHub and Markdown, send me changes in a Google Doc or a text file and I will take a look and manually make changes that apply.
A change to an open wiki will not happen at this time.
A change in software to better match php.net will not happen at this time.
We iterate on projects and this will continue to be how we approach things. We aren’t afraid to scrap something and start over. We have done this a number of times with projects.
I want to thank everyone for their feedback. I am going to move a majority of these posts to a new topic since they don’t actually apply to the survey itself.
GitHub is a good workflow.
If you really want to contribute, git/GitHub and markdown are not hard to learn.
GitHub provide user interface and tool to do it, with nice tutorial.
If I read a page of the API reference documentation and had something to add, I happily would add it, if all I had to do is just to click a “comment” button and start typing.
I would not want to get into wiki stuff, into reading any documentation guidelines first, into applying with any documentation team, into formatting any high quality documentation texts and neither into even considering to open github.
(And well, I’m not an English native, so I wouldn’t be able to write anything better than a forum posting anyway - so I wouldn’t even consider doing it)
It’s not that I wouldn’t want to help, it’s just that I have too many other things to do to actually making a living. Which I consider more important. And yes, I’m also as lazy as everybody else.
It’s as simple as making games, if you want users to play them, make them available on the app stores, where the users are looking for games, and don’t send them to github to download it first. The easier it is to play the game, the more people will do it. Reduce the required steps to as few as possible - and then reduce even some more. It’s the same if you want the users to participate in the documentation.
1 Like
If you are lazy, i think you will not contribute to write a good documentation, even with wiki, google doc, comments and forum.
1 Like
Depends on your definition of “good”. Good for me is what answers the questions I have. Bad is what doesn’t. Looking at the current API reference for Cocos2D-x Javascript, that’s probably the worst documentation I have ever seen. I tend to ignore it and google or search the forums right away. Sometimes even google translate of Chinese version history notes helps.
Even the rare parts where well written guides exist, are often outdated or feature so few examples - if at all - that they don’t help much either. Even though they are well written - and I’m sure someone invested a lot of time for it. (Don’t get me wrong, I’m very thankful for every part of documentation and respect the work very much - but the truth is, it’s just not working, at least for me)
When I invested the time to find something out from Chinese and to get it to work, I would gladly use a “comment” button to let others know about the same I found out. And I’m sure others would do this as well. Would this be “good”? Would this “help”? Would this be better than the current API reference? You decide.
Please don’t call me lazy! You are insulting everybody else.
This is totally wrong. People are not playing your game because of easy access, they play it because they like it and are engaged.
If users want to participate in writing documentation, you have to provide tools, structures and a plan. There are people around that love writing docs. Engaged people are not scared by raised entry levels, because they love what they do and understand the hurdles, which come with high quality documentation writing.
There are game developers out there, but also documentation engineers!
Look at the hurdles of game programming. What? You need to download tools and documentation on how to make games? No way, there are people out there doing this and make games…
What’s good for you is maybe bad/not enough for others. This is just personal opinion. This is not an objective argument.
I think this is just a little exaggeratedly. The worst documentation is no documentation at all.
You can always use the source, Luke!
I have the impression, that you are more searching/interested in tutorials than an API doc. Code examples can be part of an API doc, but this is not what an API documentation is all about.
1 Like
We have hundreds of videos to help you learn Cocos2d-x http://www.sonarlearning.co.uk/topicpage.php?topic=game
I could also always code my own framework. But that’s probably not what I want.
It’s always a balance between getting lots of information into the documentation, and gettig good information into the documentation!
A thought I had (for another product altogether) was presenting each chapter of the docco as something like a blog page - with comments allowed, but only approved by one or more administrators.
The same administrators could then, where appropriate, update the documentation - or leave the comment for others to read (possibly with replies.
Add this a bunch of FAQs (again as ‘blog pages’) I think it would rapidly build - but retain accuracy.
The basis could be taken directly fro your (excellent!) documentation in the Programmer’s Guid - then allow people to comment on each chapter.
The FAQs would then be like
“How can I move a Physics Sprite around the screen using buttons”
“What do the numbers at the bottom left of the screen mean?”
Again - questions added only by Admins (some could be taken verbatim, or with minimal editing, from the forums - but because the responses would be vetted, it wouldn’t be a discussion like on the forums, but considered and ‘approved’ responses.
So the forums would be a great place to discuss stuff, then when answer is ‘discovered’ it could be recommended to be added to the FAQ’s (or even added as a page of documentation if necessary.)
And in which way is this an argument at all? The source code is there, but you’re own framework is non-existent.
It’s your decision, if you don’t want it, but than you have to play with the rules or do something against it.
Mahatma Gandhi — ‘Be the change that you wish to see in the world.’
Which brings us back to the start.
[x] What documentation? It’s a complete mess.
1 Like