Documentation discussion

cocos2d-x
#14

How can you possibly tell me “how interested” I am in something?

We add features to the guide. Recently more 3D, SDKBOX, Physics, etc.

Again what? I have taken a lot of PR’s from folks and integrated all of it. Some of them I do indeed have to cherry pick.

We have done 2 iterations of IAP. Facebook is next and this will be a detailed, step by step integration.

I am sorry there wasn’t enough interest for you. We had 8 sign ups and to us, that number was great. We always want more, but the fact that even a few people took time out of their schedules to come see us and talk about the engine we make…it means a great deal to us.

Again, it isn’t fair that you try and tell us how we feel :smile:

We have people that indeed are adding JS content. I am not current of the status nor do I know a completion date.

I appreciate your feedback

#15

I am more concerned to find the right one specific case, among the many simple examples. But there must be still better to start from the needs of the majority.

#16

I can not tell you how you are interested in anything. I do not know that. It is only you know. But I can say that I do not see this interest.
This is my personal opinion.

Sorry, I do not see any changes in the chapter about 3D. But it’s possible I was not paying attention.

Сhapter about the box is not large and does not give me enough information. Only common words and description of how to install and update. It hardly took a long time to write.
But If you are involved in the writing of these documents, then I will have to say “Thank you guys, it’s very good.”

I can not say anything about physics.

I think so because, when someone on the forum once again said that the documentation is not good enough or makes a suggestion how to do better, then your answer always sounds like "We have a programmer’s guide, it is open source, you can always make a request. "
Something like “If you do not like something, do it yourself.”
This is my personal opinion. Again.

If you say in addition to this that you are currently working on chapter XXX, and if all goes well, then you finish it in a week. Then you get a ton of sympathy on the part of users, and maybe offer help, and maybe someone will be interested to write a chapter YYY. Because users will see that progress going forward, that their requests are heard and not ignored by writing standard phrases.

I am happy to hear that. This is what I needed.
Any very approximate dates?

My opinion on this subject I have described in another topic. I Hoping that you have read it. It was not very pleasant, but I tried to more accurately convey the essence.
I am sorry if it offended you.

I do not say what you feel. I say just what I feel, I see and I think.
And I wrote above, because of what I have such an opinion.

#17

Yes, this is surely a personal opinion. Our opinions differ here.

It will evolve as SDKBOX installer evolves.

Indeed, I am, along with others.

Yes, again an opinion we differ in. I always want to add to the guide. I have a number of thoughts on improving it.

It is on my schedule as one of my next items. I would imagine in the next 2 weeks as we plan 2 week schedules for tasks.

#18

I mean that in a good quality guide I expect to see the full information, not only on how to install, but also about how to use it. All api. (However, it is described in another place.)
And if Programmer’s Guide does not contain this information inside, then maybe at least insert a reference to http://sdkbox-doc.github.io/en/ in it.

Thank you guys, it’s very good.

Thank you very much! I would like to clarify that I am happy not because I need this video, I am happy because I heard a concrete answer.

I think that all who go to the forum and wrote that the documentation is not good enough want two things

  1. Be sure that you have heard them.
  2. Hear a concrete plan of what you intend to do to improve the situation.

So,
Please, could you share your thoughts on improving it?
And please say what you think about the concept of an open wiki or php.net.

All I wrote was to get the answers to these questions, not to offend you.

Thank you.

#19

Thank you for your kind words. I actually prefer the way FreeBSD is doing it.
High class, well structured docs without being clobbered by comments.

If you want high class docs, you have to utilize the system of the companies, which are known to deliver high class documentation.
Unfortunately, the majority of companies don’t spend much amounts on documentation.

This is actually I don’t prefer. The user searching for information is actually clobbered with information. You have to search through tons of comments, if you want to get specific information about a problem.

As @Actifo was already stating: it is just to much to be comfortable.

1 Like
#20

I have a lot of ideas. Obviously more content, but I was also thinking about ways to present the content better. I really like how Unreal Engine has a big, in your face, search box first and foremost.

We have talked about an open Wiki before and we decided that, at that time, it wasn’t something we would pursue. We want to make sure the information is technically accurate and the best approach. To do this curation of material is best. Otherwise, if users are editing and the content lacks quality, everyone suffers. I do see the flip side though, that curation also means adding content to it from our end. We definitely are at odds with the community sometimes on our lack of doing this as frequently as everyone would like.

Like I have said before, we are a small company with limited resources. We encourage our community to submit PR’s to help improve our engine, docs, etc. We do review those for quality and standards, which we outline here

#21

I also found a nice read about “API doc” examples:

1 Like
#22

Thanks for sharing!

#23

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.

#24

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.

#25

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.

#26

No, this is not the case, pull requests are the best way for us. The Wiki is more work to maintain in my opinion.

#27

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.

#28

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.

#29

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.

#30

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.

#31

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.

#32

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
#33

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