We are updating Cocos2d-x Documentations, need your suggestions

Please add at least 1 tutorial on camera (Follow::.....) in the docs.
There is nothing on this topic for cocos2d-x.

@sunny1304

ok, follow your command.:slight_smile:

This time i saw documentations has been improved much. But is it ok if you can provide some tutorial, or small example to introduce/how to use some feature/classes of the engine (e.x: camera tut like @sunny1304 mentioned, or parallax effects which i am trying to learn how to use it…).

It will help greatly, especially for newbie (to engine and to game development) like me to quickly get used to the engine instead of wading through every lines of code in the huge example files.

@nbtthief

Sure, I will write some tutorials in the near future. But there are also many feature needed to be developed and many bugs remaining to be fixed for me. So the progress will not be that quick, but I will try my best to improve the wiki system(including features usage and tutorials) day by day.

@owen

That’s great! It will help a lot for any beginner in future. I’m really looking forward to it.

Yes, i understand. Fixing bugs and developing new feature is high priority. Hope you (and others who contributing to this community) well!

@owen Thanks :slight_smile:

@owen

What is the plan for how users are going to be able to contribute to the Documentation?

Is the Documentation going to only be in the Wiki from now on? So no GitHub .md files, and no Docs tab, only the Wiki? I still think perhaps it should be integrated to Doxygen/Codeview, based on files in a GitHub repo. Most projects seem to use this type of system for the core documentation, and then they maybe use a MediaWiki installation so users can quickly contribute to a Wiki (that’s how Unreal Engine does it: https://wiki.unrealengine.com/Main_Page).

Can you post an updated catalog listing based on the input from this thread? The Docs for Cocos2d-JS and CocosStudio also need an overhaul. I didn’t even know there was a Cocos Code IDE since its existence is hidden in the Docs.

@odie5533

There is no real plan for the contribution side. Sorry about that. My personal plan is that I am responsible to maintain the wiki system and the community can contribute to the Github docs. I will sync the Github docs to wiki system weekly. I know this is not ideal, but Riq don’t like the wiki system, he prefer to the github way to do things. But the actual fact is that only the wiki content can be searched via google.

So that’s why I decided to upgrade the wiki system, because it is more search engine friendly.

The cocos2d-js and cocostudio part needs another guys to maintain since I am only responsible for the cocos2d-x part. We will choose some guys to maintain the cocos2d-js and cocostudio parts.

What do you mean "Can you post an updated catalog listing based on the input from this thread? "

Should I upgrade all the wiki system to the new catalog?

@owen

You could rewrite the Wiki system so it generates pages as static HTML content from the GitHub docs. That way you edit the GitHub files, then run your generator, then it updates the HTML on the site so you aren’t copying/pasting files to the Wiki. This would be searchable from Google, and it would be organized.

This is what I was saying with Doxygen. Take a look at the official Doxygen docs: http://www.stack.nl/~dimitri/doxygen/manual/starting.html

That page is generated from this file: https://github.com/doxygen/doxygen/blob/master/doc/starting.doc

So you could change the Docs over to use Doxygen, that way the Manual is in the same place as the API, and both run right off of GitHub repos. Cocos2d-x already has Doxygen up and running for the API, so it shouldn’t be that hard to add it for a Manual. I believe Doxygen supports Markdown too.

In lieu of switching systems, you could cleanup the Layout. The Wiki currently has an enormous header area that takes up 1/4th of my screen, and navigating with it is difficult. The sidebar is also too big. I made an image showing some improvements: (top is before, bottom is after) http://imgur.com/a/xaeqk

Better layouts:
http://wiki.blender.org/index.php/Doc:2.6/Manual (This actually uses MediaWiki)
https://docs.python.org/3/library/index.html

What do you mean “Can you post an updated catalog listing based on the input from this thread?”

I mean that you updated the post on the first thread with a new index, and I was wondering if you gave any thought to the other suggestions in this thread (my suggestion, and also the suggestion to consider OpenFL’s docs as a template).

@odie5533

Thanks very much. I will give Doxygen a try and update the index in the first thread with everyone’s suggestions including yours.

I will send a email to all the cocos2d-x committees to discuss what systems do we need in the end.

Thanks again for your patience and valuable suggestions.:slight_smile:

My suggestions:

Make it very clear which version of Cocos each piece of documentation pertains to - duplicate documentation is (in my opinion) better than having lots of “if you’re using javascript do this, but if C++ do that…”

Example examples examples. We’re all coders, so rather than paragraphs of text use examples to explain concepts (and pictures)

Cover memory allocation as a separate subject. How should you deal with releasing resources, say, between levels. What bits of Cocos do the memory handling for you, and how?

While it is good to have documentation for converting from V x.y to V a.b, this has a limited time-scope; better, I think, to concentrate on documentation of each currently supported version with little or no reference to earlier versions (remember there are lots of new people coming to Cocos who have never touched the iPhone version)

Scour the forum and look for the frequently asked questions and make sure they are documented; then keep an eye open - eventually the documentation will be good enough that answers in teh forums will consist mainly of ‘RTFM’ :slight_smile:

Finally, good luck! It is a daunting task to take on the documentation of something so big - I’m personally extremely appreciative; If I had more hours in the day I would certainly offer to help - I am happy to help with any proof reading etc.

We’ve been using DokuWiki internally for our wiki. You might want to check that out.

@lance_gray

could you give me some sample usage of DokuWiki?

@Maxxx

Yes, I agree some sort of duplication will be great to make each document clear and concise.

But as you said, it needs a huge amount of hours to dig into the wiki system which is not permitted right now for me.

What do you think of the new catalog I posted in the first floor of this thread?

@owen I think your proposed contents look great -
I think a memory management chapter would help me - and hopefully others - unless the memory management is being included under one of the other areas.

@Maxxx

I got it. I will add one separate memory management section.

Hi there,

I want to make a suggestion, in this tutorial:
http://www.cocos2d-x.org/wiki/How_to_Build_an_Android_Project_with_Eclipse

In section “Import Libcocos2dx Project”, even when stating that “import from you own project” in previous section, but with this statement: [your cocos2d-x root]cocos/2d/platform/android/java -> really confusing. Many people will mistake it with source cocos2dx folder.

Please change it into something like [your Game project folder]cocos/2d/platform/android/java.

@nbtthief

yes, good catch. thanks

@owen:

You install DokuWiki on your server (something like www.example.com/wiki), then users can login to add topics.

If using a different Wiki system is an option, I’d like to recommend MediaWiki.

Blender uses MediaWiki for all its documentation: http://wiki.blender.org/

Unreal Engine also uses MediaWiki: https://wiki.unrealengine.com/Main_Page

And of course Wikipedia uses MediaWiki.