Users cannot learn how to use the Timer by reading the docs.

[Johnrobmiller]

Your Godot version:
4.2

Issue description:
Users cannot learn how to use the Timer by reading the docs. There is no information about implemention, no code examples, etc. Just a brick wall of information about props and methods. This will not due.

URL to the documentation page (if already existing):
https://docs.godotengine.org/en/stable/classes/class_timer.html

[YuriSizov]

There isn't much to show. It's a node, you add it, configure its properties and connect to its signal. There is no custom code required to use it.

I guess we could add a sentence to the description that says that you can start it automatically via a property or using the start method, and that you need to connect to the signal. But I'm not sure there is much else to add.

[Johnrobmiller]

There isn't much to show. It's a node, you add it, configure its properties and connect to its signal. There is no custom code required to use it.

I guess we could add a sentence to the description that says that you can start it automatically via a property or using the start method, and that you need to connect to the signal. But I'm not sure there is much else to add.

The person who is reading this documentation knows absolutely nothing about the timer. I didn't even know it was a node, for example. When people google "Godot set a timer" this is what shows up, and the people who are reading the page are very likely noobs like me.

For people like me, this page is not useful. Adding a short paragrphs stating some things that are rather obvious to non-noobs is vital. Good documentation writers are usually very good at empathizing with new users and know how to write for them.

[AThousandShips]

I'd say it's obvious if someone knows how to use signals, which should be required if you're using this type IMO, there's a limit to how inexperienced a user we're targeting with the documentation, that's what the getting started part is for (which does instruct how to use this class, and the linked demo does use it, only change could be to link the getting started page itself)

[ALapidis]

I have never heard anyone complain that information is TOO accessible or new-user friendly.

While I agree experienced godot dev's will understand the documentation, providing use case examples in GDScript and C# is always welcome to help onboard new users as well. If the information is basic it can be skipped, but if the user is new the information can be vital to helping ease the process of learning.

I agree with the OP that there is merit to adding these, but understand if it's not a priority task. The issue comes down to keeping it new user friendly but also trim and accessible enough for fast reference by experienced devs.

[AThousandShips]

I think your first sentence isn't really fairly representing what I said 🙂

The fact is that resources needs to be managed, and there's a risk in repeating the same information over and over again to make every part of the documentation immediately accessible no matter of your previous level of knowledge

But the idea that there's no cost to adding more is not true, and in fact it does hurt accessibility, by this simple point:
The documentation is translated, making the documentation larger and larger where it isn't needed (again, not saying the information shouldn't be available, just that it shouldn't be everywhere) makes it harder for people to do the translation, and therefore makes it less accessible, rather than more accessible

Also having to sift through a lot of irrelevant information also makes things less accessible, especially if you're not very fluent in the language or have a problem reading dense walls of text, so having the documentation be compact and not verbose is a thing that makes it more accessible

People who are confused just need to follow the links and get up to speed

I hope that makes sense 🙂

[jynus]

I support the view that the manual should not, and cannot be a replacement for a course- they have different goals. It is ok to have tutorials for basic operations (First Steps), but we shouldn't have a tutorial for everything. I think the official manual should focus first on being the basic reference for all functionality, API, methods, etc. (the docs are not yet there as there are still some gaps) before trying to tutorialize everything. For example, if I already know how to use a Timer, I just want to read the manual to get quickly the available methods and properties, etc.

no code examples

Having said that, the usage of Timer is demonstrated, in context, in the "Your First 2D Game": https://docs.godotengine.org/en/stable/getting_started/first_2d_game/05.the_main_game_scene.html and that happens to be linked from the reference page!