Documentation discussion

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

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