Documentation discussion

cocos2d-x
#2

I totally agree with you, but you have to keep the difference between the projects in mind.
The documentation stands and falls with people actually contributing to it. Many successful Open Source projects have maintainers just dedicated to writing documentation. I don’t think cocos2d-x has such a system in place.

If you look at the php documentation notes. you will notice, that there are 20-30 documentation maintainers and coordinators just doing and contributing to one thing: documentation.

There are projects, where some maintainers are paid for the work they do or even have hundreds of maintainers. I don’t think cocos2d-x have that much resources or even contributors/maintainers.

#3

True, but I like especially the user comments under each entry. It’s just so easy to discuss every language feature, post code snippets and even better explanations, corrections and examples. The PHP documentation wasn’t always as good as it is today, but they had the forum like user comments system in it for a very long time already. I’m not a big PHP programmer, but whenever I needed to do some coding, the user comments more often that not were even more helpful than the “official” documentation.

And maintaining and extending the official documentation gets of course a lot easier if many users already wrote their own discussions and explanations right below each language feature.

The key is that the discussion below each statement is as easy and as open as writing a forum or blog comment. So there is lots of discussion going on. This might help Cocos2d a lot as well, as in the end it’s users writing and extending the documentation and code examples for free and answering questions right there where they belong.

#4

Documentation is part of my job. I have other parts too.

We have the Programmers Guide, it is open sourced on GitHub so anyone can help curate the guide. We have had a lot of PR’s to it. I tend to cherry pick changes as I can’t always 100% accept a PR. I have a lot of ideas for the PG as does Ricardo. I welcome every bit of feedback I receive.

#5

I use only Javascript. I wish there was a true reference with code examples for each function. The mostly one liners with the API doc are just not enough. That’s why I would love to have something like php.net with user comments - so users could discuss each function right in the documentation.

#6

We started a JS version of the Programers Guide, but it hasn’t been completed yet.

#7

I noticed the “hasn’t been completed” part :wink: A guide for JS would be really great, but it couldn’t replace a true reference of every function and parameters.

I just recommend to have a look at how php did the documentation. I think this is by far the best way of documentation and user content I have ever seen for any programming language on the web. And a very cheap way to have the users add more content to the documentation than any developer could do.

Probably it might already be a huge help to just split every API documentation into one webpage per function and add a blog like user commenting system below it. Having user discussions below every function, commenting on paramters, discussing pitfalls, giving code examples, asking and answering questions, would be a huge help.

1 Like
#8

Sure, but with “system”, I was referring to the structures and how things are rolled out and handled at the basics.
E.g. look how FreeBSD does things.

  • They have different engineering teams, maintainers and coordinators
    for specific areas. Security, Patches, PR, Documentation and so on.
  • They provide various handbooks on the topic itself, how to commit, send PR
    and what not.
  • Contributors are more involved in the process itself. If a
    contributor wants to make/add/provide stuff, they can contact the
    specific coordinators and tasks get assigned to the contributors with
    public insight of the progress, schedules and issues.
  • They also provide tools/one-stop solutions for testing, packaging and
    transferring patches directly from the console/programming
    environment.
  • Everyone can look up who’s responsible for the patch/code-review, the
    schedules, code discussion or maintenance topics.
  • The systems allow for direct community integration like @CitizenK was
    asking for. From docs, to patches, to man pages and API
    documentation.
  • There is just more visibility of the community involved.
1 Like
#9

Just have a look at a single php documentation page, e.g. for the “foreach” statement:

http://php.net/manual/en/control-structures.foreach.php

The documentation is great of course, but scroll down and look at the “User Contributed Notes” part. Everyone can easily add comments in a matter of seconds. Other users can vote if its useful or not.

This whole system, layout and functions are just perfect. There isn’t even a book which would feature such an exhausting amount of information for every single language feature. And the users added tons of content over time.

The point is, I must be able to write a comment, answer, question, code example etc. in a matter of seconds. So no wiki, no e-mail, no complicated formatting to learn or whatever else might keep a user from posting a comment right away as quickly as possible. That’s what makes such a system a success. (Nearly) No professional game developer would take lots of time to get involved in complicated documentation structures or read wiki documentations and rules and whatnot before answering to something or helping. But being able to just type some answer to somebodies question right away or correct an error in another posting etc. in no time at all, is what many developers can and will do in a minute of their time.

If you ask me, I would copy the php.net website 1:1 for a Cocos2d-x documentation website. Everything from search function to layout to features. I don’t think there is much which could be improved any further - and I wouldn’t know any better documentation for any programming language/framework. It’s just perfect and mastered the test of time very well. And, as I said, I’m pretty sure the documentation website is a very big part of why PHP got so successful in the first place.

1 Like
#10

First, you would need to define the term “professional game developer” to make that statement.
Based on your statement, a professional game developer is someone, who is is to lazy to read documentation guidelines.

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 :wink:

But again, what you describe is neither quality documentation writing, nor generating API docs or creating man pages. It’s just commenting on someones input. There are no QA processes for comments, I guess.

How about the python docs?

Because they have guidelines, (nearly) no one seems to read :wink:

http://doc.php.net/tutorial/

#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