We talked about a knowledgebase in the past but the conclusion is that you can’t read a knowledgebase like you can a chapter in a book. This is why we decided on the programmers guide. You can start reading a chapter and get the flow from start to finish. I think users would just start searching topics, read enough to get wet behind the ears and stop. Next time they have a need they search for a new term and read just enough, but not everything.
I guess I see two philosophies here. Those that search to solve and those that read to understand.
Then besides this, there are those that want to watch step by step.
I read your whole post and I understand what you are saying.
But, when I read this above, I think “we would have to document everything, for every possible combination” and I don’t know that is ever possible.
Imagine this.
We document scrollview, simple use cases, manipulating it, etc.
This solves the needs of some.
Someone else then wants a more in-depth sample of how to use a ScrollView to do something really custom.
Rinse and repeat 3
Rinse and repeat 3
Over time you can see how this stacks up. If we documented every question we got for specifics, I don’t know how we would manage it all. Plus, another way observation is not even Unity and Unreal have this level of docs. I look at their docs a lot. They are surely superior to ours.
The other thing I see is that we would need docs for:
those that have never written code, ever
those that have some coding, but not games
those that have some basic knowledge of game development, but new to Cocos2d-x
those that know enough to be dangerous, but don’t have enough experience to read the source code of the engine.
those that can read an API ref only
those that program games in their sleep, but still need the advanced under-pinnings of the engine.
We have a meeting tonight and I will add documentation to the list of topics to discuss.
Yep It’s not easy problem. Maybe we can fix that problem with an public web learning portal for samples and resources. Everyone can be an content owner. Yep, some resources will be bad (or out of date). But most of web resource systems works with rating orders, new sections today. And cocos2d-x team can also share official tutorials, samples in there. I don’t know, is it utopian?
Yep, most of my firends gave up in the setup period. Maybe cocos team can write a simple app for setup operations? (just like marmalade, Corona sdk…etc) New developers don’t like working with terminal operations. I remember, Cocos Studio was also a platform setup,build,run manager application. Maybe we need to get only that part of Cocos Studio. Is it possible?
But I’m glad to you be aware and worries of these problems. Thank you.
No slackmoehrl. We don’t have to document everything. We can have poll, or you can yourself decide about the most frequently things in a game. And things can be added in Programmer Guide which is already good for half part of basic things.
ScrollView kind of apis, I’ve noticed hasn’t changed since long. You can document the functioning of it. Rest how a person can use is upto his creativity of manipulating APIs and it’s totally on the understanding level and not the expertise level!!
You can leave such things on community to answer on forums or motivated people can start tutorials. Otherwise, everyone will always start from explaining what the heck if scrollView which in first place should have never been repeated if was mentioned in a nice way somewhere.
I’m not asking to make game tutorial! I’m asking to show the feature of cocos2d-x in written form…
Believe me!! There have been several times when I wanted to add some tutorial! But I myself end up spending unnecessary time on basic topics… You do scroll View… I (Community) add animations to it so that people can see the possiblity of its usage. My(community) part is creativity. Your(cocos) part is feature documentation.
This means we need to improve here. This is really important. What is the best approach to fix this? I can go through every setup platform doc and test it (and I have done so before a few times) but I guess I also need eyes from our community on if it makes sense. Someone posted a detailed thread about this yesterday and it is so involved, yet I don’t ever need to do half these steps. I printed that entire thread to read it in great detail and see what we should add from it.
Maybe for you, but some of the comments above and in recent thread suggest that this is a step everyone wants. Look at @luke2125 and @anon98020523 recent posts. They both suggest that we need to document all sorts of use cases, above and beyond the basic use.
Yes, I’ve also read their comments. I don’t agree with them because use case is the possibility which is ALWAYS out of scope of engine feature description. And everyone can agree that it’s part of creativity about how we can use and can be easily asked on forums.
I believe if the picture/nice description of some api is given, which should be the minimal part from engine developers. Rest they can put if they wish like 1-3 games showing different possibilities like Unity did 3 years back. It had only 3 games in its plate for 1.5 good year!!! Their 3rd game was advanced 3D type. Following their both games, made me learn game development and I was confident of me pursuing game development as my permanent hobby and in future professionally.
Rest tutorials on youtube were done by users displaying the possibilities, games, etc.
NO ENGINE, I’ve ever seen writes every possibility!
They just give simple to understand definition of everything used with working code for general use cases and the other cases if drastically different from general case, they mentioned explicitly. And diagram always helps.
For example- If scrollView is there. I saw cpptests. It hard coded the height and width which is the least practical case. You can use cpp tests for showing possiblities and PG Guide just like the idea I described above.
Sure, yes that isn’t the best case. Devs might want a scrollview that the size is based upon a percentage of the screen, etc. I recently spend some detailed time with ScrollView by implementing a landscape calendar view.
Most practical use case it calculating dynamically using screen width and height. But if we logically think, calculating height and width is the easiest thing. Main thing would be to add dynamic size elements in scrollView which quite a few ketchapp games, I’ve seen do. Even I used it, but I put a nice hack in it.
Well, if you want new users to become part of the community and using your products to make games, then wouldn’t that be a wise choice? Also, my suggestion is to have 2 sections, one for Newbies and another for Advanced… Nobody is born a programmer…
Yes, and we can’t teach it. This isn’t what we do. We are a game engine and we can’t even teach people how to write games. There is a lot of variation and creativity. We could make samples of how you might do something, but this is open ones creativity.
You can write a Flappy Bird Clone is at least 3 different ways I can think of without trying to hard. What do we show? We show way A and someone wants then way B. We end up here on this same thread again.
What we need to do is document our product in the ways that make people understand how to use it and its pieces.
@luke2125
Nope… Not everything… I am not sure how many open source community in past you’ve folllowed or seen apis of different game engines… None of them is sitting to create game tutorials!!
So, demanding everything is wrong… Obviously, why can’t they simply give a game template itself for the game you’ll release next? In that case, their engine will be most used!!
Feature description with working code of general and exceptional use cases is bare minimum responsiblity of engine developers as can also be seen in other engines. And it’s much appreciated to have 1-3 games in starting phase of engine. But asking further is being demanding. It’s a part of community and engine developers. Developers might add more things/use cases/catchy example with time… Also, game development using cocos engine can be part taken in conferences but not as integral/regular part from engine developers.
I think best solve of problem about setup period is making a setup,debug,run,project manager app just like Marmalade Hub.Terminal and working with python files aren’t easy way to setup for beginners. Is it possible?
We had the Cocos Gui app, but it didn’t work as well as we had hoped and now it is EOL’d. The screenshots you provided was along the lines of what we had hoped for.
Yeah, I also rem. it. I missed it. I raised the same need and I guess lot of other developers too… where required dependencies like NDK, etc will be downloaded by the GUI itself. Path variable also GUI can set or give instructions to set. And without any hassle, it’s ready to use in 15min-45min.
Even LibGDX follows the same.
Well, I’ve been too a couple, like Defold, Libgdx, etc…Also, I’m not demanding anything, just giving suggestions, that could help the community. If you or @slackmoehrle don’t want suggestions as per engine, documentation improvements, then it’s fine by me. [quote=“catch_up, post:87, topic:33651”]
That’s not an angry statement, just letting him know, that if @slackmoehrle doesn’t feel comfortable in adding more documents to the already library of documents, then leave the status quo. God Bless…
Yep I remember, you mean Cocos Launcher? But we were working with terminal setup way again in this time.
Imagine I’m a new developer, I’m making setup in terminal for osx, msdos for windows. Android setup is more complicated because it needs ndk, sdk…etc parts. I’m getting error in terminal window when I get an error. And environment variables don’t work stable sometimes. I’m getting error again again and again I confess that at first it is not easy at all if you’re a begginer.
It’s not easy problem. Maybe we can fix that problem with an public web learning portal for samples and resources. Everyone can be an content owner. Yep, some resources will be bad (or out of date). But most of web resource systems works with rating orders, new sections today. And cocos2d-x team can also share official tutorials, samples in there. I don’t know, is it utopian?