There's a lot of interesting demo projects in https://github.com/godotengine/godot-demo-projects, but as far as I can tell pretty much no documentation for any of them. Which makes them almost useless as demos, because they give no idea about what they're demonstrating, and a wasted tutorial resource because you have to reverse engineer them to work out what they're doing.

Unless I'm missing something?

@oznogon said: The Godot docs link back to the demos.

As far as I can tell, only a fraction of the demos are linked to like that.

To try and be a bit clearer about what my issue is: the demos are very discoverable, either by browsing the asset library website with the "demo" filter on, or getting them all pre-installed if you're using the Steam download, or even just looking at the repo. But if you see a demo which looks like it's of interest to you, my experience is that there is (a) no link back to the docs and (b) just a single line of description of what it's demonstrating (which is usually just an expansion of the title) and (c) with few exceptions, no explanation within the demo as to what it's doing (including a lack of code comments).

Which, as I said, makes them poor demos unless you're being shown them by someone who knows exactly what they're demonstrating, and an awful wasted opportunity as tutorial material.

I realise that retrofitting documentation to (checks) 78 (and counting) demos would be a serious undertaking for a project like Godot. It's just that I'm finding it extremely frustrating when I see an official demo of something I'd like to include in a game, but the demo teaches me nothing about how to do it.

In my experience being able to decipher poorly documented/horror show code is par for the course in basically every job I have worked (outside of game dev). Be that internal repos for that company, or external resources on GIT, a large part of my job has simply been understanding how someone else did something from minimal/no documentation and making my own version. In general, I've found the further you go with programming the more this seems to be true.

With the above in mind, I personally found the Demos to be a great resource. I think to anyone who has been over the docs and gotten used to the interface, the Demos are by and large straight forward to understand and commented well enough (with a few exceptions) and the fact they are called Demos and not Tutorials should be a bit of a giveaway as to their purpose. Though in hindsight I do agree they are a terrible place to 'start' despite being so highly visible when loading up the engine.

This is probably a topic worth raising on the Godot docs GIT, as there are a few ways to fix it and they may not agree. For example, I would be fine keeping the Demos as they are but think the top of the list 'Demo' should be an actual tutorial that walks the user through interface basics, showing them where the docs are, pointing out Demos are not tutorials and where to find tutorials etc. This would go a good way to introducing people to where they need to actually start because imo the Demos pale compared to the Docs for a beginner, but people always want to jump right in and that should be catered for really if it can be. And/or make a separate Tab for Tutorials that are structured to be such, though I have no idea how to make a project with popup tooltips in the Editor (like Unity tutorials), but perhaps somebody on Git does?

@Bimbam said: In my experience being able to decipher poorly documented/horror show code is par for the course in basically every job I have worked (outside of game dev).

This is so true, and I'm chronically aware how much of it I've committed over the years.

With the above in mind, I personally found the Demos to be a great resource. I think to anyone who has been over the docs and gotten used to the interface, the Demos are by and large straight forward to understand and commented well enough (with a few exceptions) and the fact they are called Demos and not Tutorials should be a bit of a giveaway as to their purpose. Though in hindsight I do agree they are a terrible place to 'start' despite being so highly visible when loading up the engine.

I suspect my own problems were two-fold: trying to learn from the demos without having thoroughly read through the documentation, and (perhaps as a consequence) not being able to decipher the structure of scenes the way I would [expect to] with code.

This is probably a topic worth raising on the Godot docs GIT, as there are a few ways to fix it and they may not agree.

Will get around to that. My first suggestion would be expanding the descriptions to be clearer about what each one is demonstrating. One sentence is not enough.

2 years later

Jeango 哦哟，What a huge guide you're working on! Godot deserves more attention in China.