There has been discussion about better documentation. A while back Ricardo and I started a Programmers Guide.
The guide has 2 goals.
A NEW user should be able to read the opening chapters and gain an understanding of how Cocos2d-x works and how to think about their game idea in Cocos2d-x concepts.
An EXPERIENCED user might skip the opening chapters but the rest of the Programmers Guide would be broken down in to chapters that cover a specific topic, like Sprite or 3D or Physics in depth.
This is very much work in progress. I spend time on this everyday.
Some of it is in Chinese and obviously I am translating this to English.
There is a file outline.md that describes each chapter and what topics we are covering.
How do you help:
Read Chapter 2 (2.md). This chapter we want to ensure that a new user can start with Cocos2d-x and understand the essential concepts. There are a few graphics at the end of āParent and Child Relationshipā that suck and I need to replace with ones that better demonstrate.
Contribute artwork. Keeping it uniform across the whole guide is important.
Pick a chapter and send PRās to add/edit content. Help us refine the manual.
Iām asking each and every user to spend time helping us out. Iād love to go to Ricardo next week and say āHey, I have more PRās that I can handle.ā, then open up a few red-bulls and get through them
As a Bonus, when we release this guide along with version 3.3:
For the top 3 users that send useful PRās I will send a Cocos2d-x t-shirt to.
For the user whom I deem helped us out the most, I will have everyone in the US Office sign a Cocos2d-x t-shirt and send it to them.
Hi,
Well, call me āThickie McThick, from ThickTownā but I donāt use Git usually, so Iām not sure how to go about even reading what is there already - is there some sort of .md file editor somewhere I can use.
We are working hard on this. Ricardo is ensuring technical accuracy and overall flow. Iām working with engineers to gather material as well as content, grammar, etc.
Chapter 2 is really important. If anyone has thoughts Iād appreciate hearing them.
@Maxx - you can click each .md file and view it directly from GitHub. If you want to add content then I think you need to fork the repo and then submit a pull request with your changes.
If you are struggling, you could always e-mail me with your changes, thoughts and I can look at integrating it as I would will the pull requests.
@Maxx@slackmoehrle - if you just want to make an edit in one go, github letās you click edit on any file and itāll manage forking and creating pull requests for you
BTW, what do you guys think about putting all code samples in platform-independant (cocos2d-api-compliant) pseudocode? I think the C+Ā±only samples are something that may frighten newcomers.
Or, itād be awesome if we could implement something like the code viewer over at MSDN (where you have a little box with tabs, and clicking each tab will show code samples for doing the same thing with different languages), althought I donāt know if this can be done with .md files (and itāll be harder to maintain for sure).
Hello, itās really nice you add this.
Firstly, in Appendices, the start should be Prerequisites and not Android (Terminal) so all links miss the good target.
My question, as a mac user, I wanted to install a version on windows.
On G.md, you write VS 2012+ and I try on VS 2012 Express And Windows 8.1.
The problem is that VS2012 Express say it is not a valid project, so canāt make it as start up project.
I had a little time and produced some docs draft myself. This is how I would approach it. Maybe you can take it as a suggestion or even build it up like this.
In the docs you can see several aspects like images, referencing to images and sections, inline code highlights and API documentation. By using typesetting frameworks you can create a consistent looking and professionally documentation, which is in sync with the actual API.
I uploaded a zip archive with pdf and html version in it.
cocos2d-x_docs.pdf is the pdf version.
cocos2d-x_docs_html.pdf is the html version.
Sphinx supports many features through extensions, which rely on reST. You would have to look how Pandoc would convert them. E.g. the pictures in my doc are not drawn, but programmed/generated through typesetting with TeX/LaTeX/TikZ/PSTricks.
Glad you like it, but itās far from perfect. I canāt follow you completely. What is it you are asking for? You want me to include your blog into my docs or do you want my doc included into your blog?
