Documentation discussion

cocos2d-x
#11

[quote=“iQD, post:35, topic:23885”]
You are mixing professional documentation writing with commenting on a wiki. These are two very different things.

Any professional (game) developer has to read and will read guidelines. This is just part of a QA process. If (nearly) no professional game developer would not do it, then explain to me, why so many professionals are contributing to first class Open Source projects then ;-)[/quote]

My point was that users should be able to just press a “comment” button on a documentation page to leave their input, comment, question, answer, code example etc. Most of the professionals (as in having the experience to give high quality input), probably have other things on their minds than to join a documentation team, read documentation guidelines and get involved with documentation groups and structures and to write and format high quality documentation. But just commenting is quick enough for many to happily participate.

The python documentation for example is great but looks like it was a lot of work and is yet still very short compared to the PHP documentation. Just look at the foreach example I linked. There is more about a simple foreach statement than any developer may ever want to know in his life :wink:

An API reference with one statement per page and the ability to add user comments may expand the cocos2d-x documentation tremendously in a comparably short amount of time and with fairly little work from the development team. And picking up good comments may even help the “real” documentation team with their work.

#12

In the first
Hello all!

@CitizenK
I like your idea in general. But not sure if the comments on the article would be too much it will be comfortable. Because some engine concepts are deep and complex.
What do you think about the concept of Wikipedia?
I’m not saying that the comments are bad, just not sure.

@iQD
I see that you are very experienced and erudite man. Just wondering what the concept of the organization of the documentation would you prefer?

@slackmoehrle
I apologize if my first post on this forum was unpleasant.
This is because I wanted to help improve the documentation (I even have a few drafts of articles written on the paper. Yes, I use paper for these. I just still can not bring myself to type it on the computer and make a good illustration.), But I do not see enough interest in the improvement from your side.

  • I saw that you started Programmer’s Guide (hooray, hooray)
    you describe the basic concepts in it (now it is more like a Beginner’s Guide)
    but then you forget about it (I do not see any significant changes for a long time),
    if users write something else - “it is good, if not then we will not be anything else to add”.

  • I read that you plan to create a training video about the sdkbox. Therefore, apparently, Sonar Systems refused to create a same video. But I do not see any progress in the creation of your video. And I see the announcement about the meetup, which seems almost no one is interested.

It all makes me think that you are not interested in improving the current situation.

But it turns out that you are working on a version for the JS. You’re really working? I hope that yes.
And you have some ideas about the guide. By the way, what are these ideas?

Maybe things are not so bad as it seems. And maybe you just should more often share plans and degree of readiness.
“We are working on it” - it is not too encouraging response.

Regards

#13

I don’t like Wikis. They are great for huge amounts of lexical information, but they aren’t good for structured language references.

Seriously, have a look at how php.net does it. As far as I know they moderate the comments and there is also a voting system to up- and down-vote comments for usefulness. So the users also do the QA.

Because more general comments tend to get more votes, as they help more people than very special cases do, and the comments are sorted by number of up-votes, the system will already move the general information up and the more special cases down, which makes it very natural to read.

The key is to make it as easy as possible. If I remember correctly you don’t even need an account to add comments. There should also be no additional browsing, so the “one-page per API function” is very important. Comments just added below. No special “comments page” or anything like that. Writing comments should also be as quick and easy as possible, with (code) (/code) being the only formatting option. No linking, no bold format, no images, just text and code.

If some functions get too complicated, just split them if it is needed. But usually it’s fine.

But even though the system is very easy, I wouldn’t expect a flood of comments coming in. It will still be hard to convince users to write good comments and not just the same question over and over again (moderation is likely required). And there won’t be like 100 good comments a day. It would be great already to have one good comment per week. But again, have a look at PHP, many comments are many years old - and still very very useful.

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