Godot-docs: Split tutorials into Mono and GDScript

[docquantum]

The tutorials were originally written for GDScript, but as the popularity of Mono grows, it makes it harder to go in depth on why things were implemented a certain way in each respective language.

C#'s strong typing means many more hoops have to be jumped through when doing something like a parent class for weapon type and trying to call a common method between the child classes if they are all differently typed (RE: FPS tutorial Pt. 2).

Being able to split the tutorial completely into the two languages, rather than just code tabs, would be better as it would make it easier to explain what's happening in the code without getting too spaghetti-like in explanations or long.

Thoughts?

EDIT: A question to ponder is the best way to do this. Maybe making separate sections with completely different documents? Like under a tutorial, make two sub-chapters for each language respectively.

PS: I'd be willing to start with the FPS tutorial since I've been going through and doing everything in C# anyways.

[pycbouh]

Do you imagine the whole Tutorials section being split into two different languages? This does not seem feasible or even usable by readers.

Also, I'd argue, that these tutorials are aiming to explain how to use Godot and script some very basic logic, not how to code properly. Most of the stuff should be provided in the minimal working state and explained on a need-to-know basis. If any in-depth explanation is needed for C# side of things in general, like what you describe, it is better be put into C# section here as a compendium of tricks and caveats. Notes to it can be added in C# tabs, so that GDScript users aren't bothered by them.

[clayjohn]

I agree with @pycbouh I can see a "C# notes" section at the bottom being very useful.

This is likely a better issue to deal with on a case-by-case basis. Most tutorials won't need additional information and C# tabs will be fine.

One other consideration not mentioned by pycbouh above, is the effort of creating and maintaining the docs. If we were to strive to provide a C# version of every tutorial, we would be effectively doubling the maintenance burden of docs. This is troubling as the docs are already sorely in need of more love.

[docquantum]

Makes sense. I guess the thing that makes the tutorials a little harder to follow when using C# is when the tutorial keeps referencing syntax and style related to GDScript, which is where this is coming from. But a C# notes would not a bad idea, or maybe just adding code comments in the C# tab to describe why something was done when compared to the GDScript version (such as downcasting).

[docquantum]

Any suggestions on improving that specific problem (where naming is different because of style differences between the two languages)? This can be seen a lot in like the FPS tutorial, pt 2 more specifically if a csharp version were to be adapted (I'm working on it now).

[marcospb19]

I support splitting the tutorials into two different pages.

Imagine a tutorial showing coding examples in C and Python, if they are in the same section, I can tell that the tutorial will lose quality for a person that wants to learn only to a specific language, hiding important details, coding is complex and languages are very particular.

C and Python are very further apart from each other than GDScript and C#, but those two languages still have their limitations, recommendations and differences.

Often the tutorial says vague stuff like:

If you want to move using the world space directional vectors, you’d do something like this:`

Instead, it could say.

To to move using the world space directional vectors, you can use the translate method to rotate/manipulate...

This is just an example to show that the explanation in the tutorials constantly avoid talking about function/method/variable names because the languages are different. This is bad, the text doesn't feel connected to the code, information is hidden.

So, even if you connect the code to the text, names are different, and the C# readers have to struggle reading the tutorial with the __wrong names__.

The shader tutorial delivers a better explanation of everything, I suppose that is because there's only one shader language in the tutorial.

[marcospb19]

I'm also strongly against a big C# notes section at the end of the document, the jumps (back and forward between the tutorial itself and this section) may screw up the C# reader experience.

At least, it won't bother the GDScript reader if the section is collapsable (and collapsed by default). Imagine having to scroll down through this section that could just be somewhere else (and if you answer "so we'll keep it small", you're again limiting the C# tutorial explanations).

[marcospb19]

I'd argue, that these tutorials are aiming to explain how to use Godot and script some very basic logic, not how to code properly.

Well, let's change this thinking! Tutorials should teach the basics while also teaching how to code properly on real case scenarios, as we suppose people are doing the tutorial to learn the language and develop the best that they can.

Let's debate more about this, I would like to contribute to this change knowing that I can write detailed explanations instead of just you’d do something like this:, of course I'm not saying that the tutorial is bad, but that two languages in the same page causes this type of problems.

[docquantum]

The point about doubling the maintanance of documentation is very valid however. And seeing as C# is behind on GDScript in support and adoption, splitting at this point in time might not make a whole lot of sense. However, I do think that splitting would be the best option for readability and usability. When Unity used to have JS script support, that's what they did since the differences between how you would achieve things in the same manner were quite large.

Like I mentioned in the original post, the FPS tutorial suffers greatly if trying to adapt the current GDScript implementation for C#. GDScript's way of handling classes makes it so that you can easily have child classes and access methods from a parent's class of those children. In C#, you have to do down casting and before you can do that, you have to make sure the class you're accessing is the type you want to keep things safe, so you need a lot of conditionals to do it (unless someone knows of a better way). Being able to split the tutorial into two languages means you can have two solutions for the same problem that act upon the strengths of the respective languages.

Another argument for splitting is that as C# evolves with its current support in Godot, it's easier to keep the two separate and update the C# changes, as opposed to going back and finding all the C# snippets and updating them.

[pycbouh]

There are following points to consider:

• There is an ongoing effort to reorganize the whole documentation (#3390); part of it is in removing unnecessarily in-depth tutorials, like the FPS tutorial, from the official documentation in favor of other community efforts to provide similar guides. This means that big articles that suffer the most from the presented here issue are likely to be removed or rewritten in a much more directed manner, thus reducing any confusion.

• There is a notion about C# being a privileged language compared to other third-party languages supported through GDNative. While it's unlikely that C# support will be dropped in its current form in favor of another GDNative binding, documenting it is still a secondary thought for the most part. For one, there is no separate class reference, and even the API differences doc is outdated and missing some parts of it.

• While it may be convenient for beginners to have their full experience of making a video game completely within the Godot Documentation, it's unlikely that there is going to be a shift towards providing some basic coding or designing guidance within these articles. Partially, this is also covered by the aforementioned effort to streamline the docs. Partially, it's just unreasonable to handle both Godot side of things and general programming/game development side of things. There are plenty of resources to learn that.

For these reasons, I feel like writing docs in a language-neutral way and providing comparable code samples with an occasional note about C# or GDScript implementation detail is the only feasible way right now. If there are general patterns about making a Godot game with C# that are worth a detailed explanation, there is always the Scripting section.

[neikeq]

There is a notion about C# being a privileged language compared to other third-party languages supported through GDNative.

This is because C# is officially supported in Godot.

For one, there is no separate class reference

I would like to add one. However, it's not as simple as going with the GDScript/C# tabs method. The APIs are not always 1:1 and in some cases there are extra members or classes.

The easiest would be to add a new Godot C# API section but I don't know if others would agree with that.

and even the API differences doc is outdated and missing some parts of it.

This is my fault. I did very little work on documentation so far. I should be updating that page and adding other pages with gotchas and useful information.

[pycbouh]

This is because C# is officially supported in Godot.

I meant it in a way, that it can be perceived as unfairly privileged. It was mentioned at some point in various discussions, that if C# support was added now, it would've been as a GDNative binding rather than the way it has been.

I did very little work on documentation so far. I should be updating that page and adding other pages with gotchas and useful information.

I think, this is the best resolution for the current problem. Maybe worth making a "tracker" kind of issue to list things that are missing or in need of updating about those pages, so that the community is able to lend a hand.

[docquantum]

Here's a thought, similar to how Unity has a "tutorials" section of their website, what if we were to emulate that? Have a new site with self enclosed in depth tutorials, and instead leaving docs to be reference and manual. This could be a wiki style system or something else that would be suitable. One downside to this is that it would fragment the documentation and again require more maintenance in the short term, with possible long term benefits (locking certain tutorials to certain version similar to how Unity notes what version the tutorial was written for). This of course could all be done in the current docs, but as was mentioned above, it looks like in depth tutorials are being written out.

[pycbouh]

@docquantum This is exactly what #3390 is about, partially.

[mhilbrunner]

See my comment here. And yes, this is mostly what https://github.com/godotengine/godot-docs/issues/3390 is about.

[marcospb19]

Avoid GDScript inline code in tutorials where possible

I think that this worsens the tutorial itself (already commented about this here).

Talking about the issue of this tutorial in specific, isn't it viable to create GDScript tutorials and then adapt them to C# by copying the file and making the necessary changes?

[pycbouh]

isn't it viable to create GDScript tutorials and then adapt them to C# by copying the file and making the necessary changes?

The issue is not with a one time creation, but with maintaining two copies when the engine is ever-evolving. Also, layout changes, style changes, various other improvements would require double the work.

[NathanLovato]

Note we're removing long, step-by-step tutorials from the docs. See #4074. As far as step-by-step tuts with inline code, we should be left with Dodge the creeps and a 3D intro tut in the end. That should partially address the issue, as, otherwise, you need to write and maintain two versions of each tut in parallel. And the resources aren't there for that at the moment.