Where to get a tutorial?

Within reason, absolutely. I pass along all feedback too.

However, there are some things I just can’t fix. When a user says: “The documentation needs to be better”. I can’t fix that, at least I can’t guarantee it.

Why? Because it is to generic. The thing is, we provide documentation based upon what we think most new users need/want to know. If there are topics you want covered. Tell me. Provide some thoughts on the topic. Provide some sample of how you got started. Every little bit helps get it started. Make a GitHub issue in the docs repo so I see it. That is one of the repos that I live in.

Telling us to make a sample game (which I am doing now) isn’t a great idea either. Why? Because if I make a small platformer game, it doesn’t help those that want to make a game that isn’t a platformer. They will just hunt and peck for code and then still need and ask for more example, more samples, more of everything. That being said. I’m making a sample game. We provide cpp-tests which is where you should be looking for how functionality is supposed to work. When you start combining code to make your game you have to make concessions and adjustments and that perfect working sample isn’t so perfect anymore because it doesn’t teach you how to adjust your code, combine your code, think out side the box on your own project.

I use cpp-tests when I need to see how something should work. However, in every one of my 35 games, it never goes perfect. I have to do something unconventional to get the result that I want. How did I realize this? I looked at the API Ref, I read cpp-tests, I read books on game design and simulating the real world. I’ve posted pictures of my bookshelf before on these forums I’d be happy to take some new pics.

The thing is, being a programmer is more about understanding than the code you write. I’ve worked jobs where I wrote less than 200 lines of code in a week, but that code was super tight, documented, tested, tested again, tested yet again and didn’t fail. I had to put thought and reasoning into the idea. Nobody was going to teach me that, I had to learn that over time. I’ve also worked jobs where you were judged by the amount of code you wrote, bugs fixed, etc. This produced a sloppy, spaghetti mess. Other programmers cound’t easily pick up the code and run with it.

My point to that above paragraph is we are in a hard place. We get a lot of new users that need help learning c++, need help learning game design concepts, need help reading an api-ref, expect a full working example that they can compile and play, expect 24/7 answers to every question on these forums, expect me to reply to every PM I get and then send me 2,3,4,5 more when I don’t reply within an hour. How do we solve this.

If I put time into writing a playable sample what if it doesn’t help users that want to write a different game?

If I spend time writing more content in our docs, how does that help those that don’t want to read to understand, they want a working, playable sample?

If users help us and submit issues they want documented with some initial content, some sample code (even if it isn’t working), it at least shaves off time in writing the rest of the content. I have used people’s explanations from these forums in our docs (with permission). Why? Because it was good, it gave me a jumping off point and it would help those who may need that concept explained in the future.

if (open-source == community_involvement)
{
    return success_everybody_benefits;
 }
else
{
    return you_get_what_is_provided_to_you;
}
3 Likes

What is the current English documentation? Is is the api-ref? Is it this? If it is, what is the best way to contribute to it? Can there be a version tied to the docs, ala Django, where you can be sure that the docs you’re reading are tied to the version of the game you’re using?

Is there a better way to request very specific parts of the documentation to be improved on?

edit: the docs link the GH for it, so that question is moot GitHub - cocos2d/cocos2d-x-docs: documentation of cocos2d-x

Creating a GItHub issues puts your request straight in my view. I can’t not see it.

Creating a GitHub issue with some thoughts about what you want and code etc moves it higher up because chances are I can work it in to my edits I do already.

Providing me an awesome topic with text and code that I can just put right in with minor formatting edits gets you credit in our docs and my personal appreciation for helping make my life easier as well as making a useful contribution to the community. Plus a beer or 6 if we ever cross paths.

1 Like