As far as the learning materials go, I personally wish there would be more focus on written docs instead of video tutorials. Video tutorials have their place for getting people started, especially in the editor and art pipeline but there are very little reasons to have them for shader programming or programming in general, properly written docs will help more people and are what most programmers want. Nobody really wants to sit and watch random tutorials wishing people will mention the thing they want to know at 1 hour mark in the video.
We've had this discussion many times in CryCommunity Slack, but I'll summarize what I'd personally feel most important in the learning materials from game programmers point of view:
1. Visual graphs and overviews on all CE systems and frameworks so that people who use then engine actually understand what they are dealing with
No more guessing or false assumptions. Current docs do explain some of the systems but that info is usually hidden in endless paragraphs of text. Please, put more visualization, those graphs etc that make these connections between different things crystal clear. To make example of this, look at this page about CryPhysics: http://docs.cryengine.com/display/CEPROG/CryPhysics
and then look this lumberyard doc page: http://docs.aws.amazon.com/lumberyard/l ... reads.html
. LY doc has graph that immediately tells how physics execute in the bigger picture while in CE doc the info is hidden in the text and you have to figure out what the words really mean in this context. More graphs the better IMO to avoid confusion. Few more examples on why graphs are useful:
(look at the graph in the end, for a programmer, this is priceless info), GameFlow
If all those graphs in those pages were just text or list, it wouldn't be as easy to understand the relations between the things.
2. API docs that actually tell something useful
Just having API docs that parse the function declarations and parameters doesn't really do much good. When you actually use the engine, you need to know how it individual things work. Nobody knows everything so API docs should be your go-to place for telling how to properly use the functions and classes in question. How Unity does this is great, for example lets have a look at https://docs.unity3d.com/ScriptReferenc ... ycast.html
, you open the page, looking at how to raycast, not only they explain every variable, they also provide direct links on how to setup and understand every variable you need to use there, like link directly to https://docs.unity3d.com/Manual/Layers.html
on LayerMask. Then after that, they tell what the function returns and describe briefly what it does.
Here's one important thing to note: there's a huge difference in describing what the function actually does and just spelling the function name there (for example, only putting "Casts a ray" there would be terrible description as the function name already told us that and it would provide zero value for the reader).
Also after description, they actually give out code snippets that show how you can use the thing, in CE and c++, things like these would be really valuable as people wouldn't have to search around the proper usage, they could just open API docs and immediately use the thing. So the key thing I'm trying to tell here is that please try to make the docs informative and easy to navigate. In ideal case, you'd only use search bar once and then you could navigate to the relevant pages directly instead of doing separate searches for everything.
3. Have programmer introduction docs to get new users on-board faster
Pretty much what the topic said. At the moment, CE template code is basically closest thing to this but it only gives you the entry point to the engine + new users might not understand what they see there. For example, Unreal does this to get new users up to speed: https://docs.unrealengine.com/latest/INT/Programming/
4. Current docs and tutorials aren't organized in any way
While trying to find the CryPhysics page for 1st point, I had to search with google and internal docs search for quite a while to even find the right place. There are tons of different physics articles in the official CE docs that all discuss different things but they are not linked under same subsection at all. It's incredibly difficult to find anything that's related to your own interest unless you actually know such doc page exists somewhere deep in that jungle of random documents. And you pretty much need to know such document exists before you can even find it. Current documentation looks like things have just been added along the years and nobody enforced the structure. It's already bad enough that most editor side things still have only CE 3.x docs but then there's CE V docs, technical docs, beta docs, website tutorials, beta tutorials, youtube tutorials, vimeo tutorials. These all are scattered around and many are not up-to-date. It would benefit to have all tutorials in one centralized place for example.
5. There's no indicator what version of the engine most of the docs and tutorials apply to (besides CE 3 or CE 5)
While dates can hint something, often even old docs get updated with some small corrections so it's impossible to tell from dates alone if the learning material is relevant for the current engine or not. If you look Unity or UE4 docs, they are really exact on what engine version those docs are for. Also those small corrections and engine updates is one reason why I'm not fond of any video tutorials that go beyond the basic editor usage: they are almost always outdated and you can't easily update parts of the video like you can with written doc page.