The Signals in code getting started page is scaring new users

[shak2]

This page:

https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html

The signals in code part is meandering, confusing, obfuscating a vital Godot functionality that is deep down trivial to learn, powerful, and useful.

Signals are easy.

Make Signal:
Signal SIGNALNAME

Connect Signal:
SIGNALNAME.connect(FUNCTIONNAME)

Make function:
func FIUNCTIONNAME(arg1, arg2, ...)

Emit Signal:
SIGNALNAME.emit(arg1, arg2, ...)

That's it, that's signals, look how easy it is.

But everyone I send to that signals getting started page wants to quit Godot. Something is very wrong with it and needs fixing.

Godot is open source, why don't YOU fix it? Because my fix would be deleting the entire code part and replacing it with the 8 lines above. Such a drastic change would be rejected unless done by a senior editor. So can we please get a senior editor to look at that page and fix it up. Thanks.

[AThousandShips]

Such a drastic change would be rejected unless done by a senior editor.

They would not if the changes are valid, that's not how the workflow process works, anyone can contribute anything, assuming they are capable

[theraot]

I do recognize this issue. I remember rewriting the exmplanation of signals due to a similar situations.

---

The following is my take on what the problem is:

What happens is that the article in question is a tutorial. And in your case you want a reference. So, it is not the right thing, although I see the right thing does not exist how you want it.

I can imagine people on the recieving end taking it wrong: they might think - upon a glance and not really reading - that they need a new scene to be able to make a signal (which is not true), and it might be intimidating to read due to length.

I can also imagine why the tutorial cover that in the same article: it makes it a full tutorial. At least the relevant part is that it covers how to connect singals in the editor, which you don't seem to be interested in, but it should be covered somewhere.

The context of the tutorial is helpful for some people. As they find that they remember what they learn better if they learn by building something. But not everybody is like that.

---

The following is my take on the solution:

I'd say the documentation needs something like the editor introduction (https://docs.godotengine.org/en/stable/tutorials/editor/index.html) but that covers more advanced topics. In thic case, the documentation could use an article on signals that covers only the visual part, and links to where to learn more about singals. In fact, the documentation could use an article on each of the docks and each of the panels, organized in that way that is easy to find.

And the reference page on the signal class (https://docs.godotengine.org/en/stable/classes/class_signal.html) could be expanded with more examples (notably it does not have an example for emit which is very common use case, and get_connections is complex enough that it would be better with an example).

For your use case, you would share the latter. Other people might share the tutorial that already exist, or - if created - the documentation on the signals dock that I'm suggesting above, depending on the situation.

---

This is all my take, of course.

About the change being rejected, in my personal opinion, adding (be that the documentation on the the signal dock, the examples on the class reference, or something else) would be less likely to be rejected as no documentation would be lost.

You - of course - can decide to make a pull request, or leave that to other people. If you make it, you would be getting feedback on the pull request, so you can improve it until it is accepted.

[Calinou]

• See also Add 'Signals, concise example' documentation page godot-docs#9460.

I think the closest to what you want right now is the Signal class reference page.

[manujarvinen]

As a proposer of that Concise Example page, yes, this proposal of shak2's is even better than mine. But I don't understand why we would need to settle for 'closest' we can get. I still rarely understand the reference pages, even though they're nice and to the point. I need super clear examples of how things work. And I'm very sure I'm not alone. That's why I propose the Concise Example and yes, I also support this proposal. Maybe we can together come up with a way to say to new users how simple signals actually are. I hope.

[theraot]

I had not seen that. I think it is a good idea, and it can coexist with references and tutorials, no problem. In fact, it is not a problem to have different examples in the reference page, because ideally these pages would link each other (in fact, that would be my feedback for the pull request: add a link to the reference page).

[manujarvinen]

I'm proposing to combine this shak2's suggestion with mine, like so:
godotengine/godot-docs#9460 (comment)