Godot-docs: Avoid GDScript inline code in tutorials where possible, confusing for C# users

[akien-mga]

See godotengine/godot#20989.

[bojidar-bg]

Can we make the inline texts switch between C# and GDScript along with the tabs?

[cbscribe]

In my opinion, this is a slippery slope that leads to less effective tutorials. If I can't mention the code in the text directly, then I can't effectively explain what's being demonstrated. I would have to come up with roundabout ways to reference the code without using function names, etc.

This is especially problematic in a beginner tutorial like the "dodge" one, where there needs to be a lot of explicit explanation.

Can we make the inline texts switch between C# and GDScript along with the tabs?

sphinx-tabs doesn't support this.

[bojidar-bg]

sphinx-tabs doesn't support this.

We might try to cook up some support for it, if deemed necessary. (just saying)

[mhilbrunner]

In the end, this is just a result of there now being two languages (three if we count Visual Script).

If we had unlimited resources, the proper way would often be completely seperate tutorials per language, as the languages differ in their features and you would often implement things in maybe similar, but different ways depending on the language.

This was very visible with the FPS tutorial as well.

This is a point in favor of focusing more on API docs, less on full blown tutorials as well (as proposed in https://github.com/godotengine/godot-docs/issues/3390):

Better we document the API for each language cleanly and let others do focused, language-specific tutorials, than trying to provide language-agnostic tutorials that try to wrangle everything into a single document, ending up confusing (and in the worst case, teaching very unidiomatic practices to people).

[NathanLovato]

Considering:

1. It's difficult to act on this issue.
2. We're removing most instruction-driven, step-by-step tuts from the docs ( #4074 ).

I'm closing the issue for now.

To chime in, I second both what Chris and Mhilbrunner said. There's just not much we can do aside from duplicating the docs, and it'd be near impossible to make accessible tutorials without inline code. Both Chris and I have been writing tuts for a while now, and you need to reference code in the text to help guide people, especially users with limited programming experience.