Godot-docs: Add examples to the Godot API documentation

[rogeriodec]

The Godot API documentation is technically perfect, it covers all properties, methods, signals, etc.
At the same time, it teaches NOTHING.
For those who want to learn the basics and concepts, seeing long-winded documentation is the same as nothing.
I'll show you an example, a template for anyone who wants to learn quickly: Autohotkey.
All the commands, functions, methods, absolutely everything, besides being technically well documented, everything has VARIOUS PRACTICAL EXAMPLES.
In this way, the apprentice observes the examples and LATER will understand technically how it works.
And I assure you: the learning curve increases exponentially.

Ironically, people who know a product deeply to the point of doing good documentation, at the same time are those who are completely committed to the development of the software, this way they have no time to invest in good documentation.

But this is a vicious cycle.
If you can invest more time in better documentation, you will have more experienced users and consequently more people who will be able to collaborate with the development and at the same time with the documentation.

[clayjohn]

First of all thank you for the thorough suggestion. This comes up frequently. Most recently: https://github.com/godotengine/godot-docs/issues/2190 (please read the responses here)

Personally, I agree with you completely. And im sure the core document writers do too The reason we havnt done what you suggest is not because we dont see it as a better form of documentation, its because we completely lack the resources.

We have no way of getting more people writing docs. When you ask users to help they often lash out at you.

One final point, with the current structure of the docs, new users should not be going to the classref to learn, it is intended for more experienced users. Instead, new users should rely on the tutorials to learn the basics. I understand that sometimes the feature you are trying to learn doesnt have a tutorial, but those of us working on the docs are trying our best to cover everything.

[NathanLovato]

At the same time, it teaches NOTHING.
[...] seeing long-winded documentation is the same as nothing.

You seem frustrated and I can understand that. But to me, comments like these don't help.

We're aware of many ways in which we can improve the class reference and the manual. There are more tutorials, translations, and content added to the docs every week. There's been work on examples since the previous release. That's just a massive undertaking and too few persons are willing to help for it to keep up with the engine's growth.

There are many tutorials, including a step by step guide to get started. Also, open source demo projects. You'll find plenty of examples there and in other places on the web.

Improving the docs is not a job for developers alone: you need writers, and technical writers to produce great documentation. People who will not only write examples but who will make them accessible to those learning to use the engine.

To get good examples and help more beginners, we need more users to help. You don't need to be an expert to write code examples. The core team and all contributors are busy, there's always plenty to do. We're quite a few working on educational material already. If you want the ecosystem to evolve faster, we need more persons like you to help.

[rogeriodec]

I'm a beginner in Godot (I have only 10 days of use), but I still have 36 years of IT experience and I've worked hard with documentation and videos.
Once I've gotten a little more basics and basics from Godot, I'll be available to help.

[NathanLovato]

We'll be glad to have you on board :relaxed:

[justchen1369]

Is there a centralized location from where I can see what needs to be done in the Godot docs?

[clayjohn]

Yes, here on the GitHub page under "issues" pick one and start going. :)

If you prefer to work on the class reference you can go onto the main GitHub page and look at issues tagged "documentation".

[NathanLovato]

Here is where you can find issues for the API reference: https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation
The classes use XML data and you need to edit these files: https://github.com/godotengine/godot/tree/master/doc

[NathanLovato]

You have detailed contribution guides here, including the writing guidelines: http://docs.godotengine.org/en/latest/community/contributing/index.html

[NathanLovato]

And the style guides for the various languages available in Godot are here: http://docs.godotengine.org/en/latest/getting_started/scripting/index.html
E.g. when writing code examples.

[NathanLovato]

Closing because this is happening, although little by little, and some contributors are aware of the issue. Now, we'd need people to request specific examples to put in pages where they'll be most beneficial.