Godot: Approaching Documentation with a wider audience in mind

[golddotasksquestions]

Godot version:
3.0, 3.1

OS/device including version:all

Issue description:
A supposed "lack" of documentation has become a meme within the community. As it has been discussed on Reddit multible times, I'm opening up this issue as a place to discuss, comment and keep track of progress.
General consensus seems to be, that as Godot grows, so does the documentation audience. Therefore a form of documentation is needed which is comprehensible for people from all areas of development, not just people with existing programming background. The Gamemaker documentation has also been mentioned a few times as a good example of archiving exactly that and could be used as a general guide in terms of structure.

[Feniks-Gaming]

I am not sure how much to add to this. General impression I am getting from documentation is that it is written by people who know programming concepts well and for people who also know most of those concepts quite well. Documentation uses some jargon language like mentioned before on reddit "query 2d space" in Raycast2d node description.

While this was once fine when godot community was composed of passionate knowledgeable people. This is no longer a case. Godot is often offered as beginner friendly alternative to Unity and Game Maker. However at times documentation is anything but beginner friendly. I feel that using simpler pain English terms could make understanding the engine by beginners easier while it wouldn't take anything away from experiences users.

For example look how much easier to understand is unity description of what Raycast2d is https://docs.unity3d.com/ScriptReference/Physics2D.Raycast.html over Godot explanation https://docs.godotengine.org/en/latest/classes/class_raycast2d.html

Other quite important issue with godot documentation is that it explains what things are but not why, when or how one would need to use them. As a result it is difficult to understand what role in actual game each node could have and why.

Good visible examples like for instance presented by unity docs:

Raycasts are useful for determining lines of sight, targets hit by gunfire and for many other purposes in gameplay.

would be extremely helpful in understanding purpose of those nodes.

Unity and Game Maker both go further by including a commented code sample that shows practical use of a class or functions.

Using our Raycast2d example I think it would be great to add mini tutorial to the node showing how raycast can be set to simulate line of sight for an instance.

General consensus on reddit is that it's near impossible to learn godot with just documentation and without using additional tutorials. We should strive to create documentation that is sufficient source for anyone who wants to learn how to use Godot even if they are beginner programmer.

[reduz]

Hi guys, you are barking at the wrong repository. It's nice that this is discussed but please open issues in the relevant tracker:

https://github.com/godotengine/godot-docs/issues

Closing.

[golddotasksquestions]

Thanks for the note. Done: https://github.com/godotengine/godot-docs/issues/2190