Discussion: Dealing with Disambiguation in the Godot Manual

[betalars]

This has popped up in my mind when I was thinking about enhancing the documentation of Addons and Plugins

I think the difference between plugins, addons, gdextension, tools and modules may not really be clear to many users and could need a disambiguation wiki page.

A good place in my opinion would be a dedicated disambiguation section in the manual. However that would 100% leave the scope of just enhancing the plugin/addon documentation. I think it would also need more than just one use-case to warrant its existence.

Hence I am opening this discussion to collectively think about:

1. are there other areas in Godot that would benefit from disambiguation?
2. what is the best way to implement that?

[tetrapod00]

In this case, a new short page in the Plugins section makes sense to me. If it's very short it could also exist in the index page itself.

At first glance, for other cases I don't think we need a full separate disambiguation page/section yet. I don't really think it fits the current form of the manual. In most cases, either of the following will suffice:

• A see also box on one or both of the relevant pages, if one is very commonly confused for the other.
• A section which describes the differences between the options and suggests when to use each. This isn't really disambiguation but it is explaining multiple options and clarifying the differences between them.

Some existing sections that are sort of like a disambiguation:

• See also box on the Export section redirecting to GDScript and C# exports: https://docs.godotengine.org/en/stable/tutorials/export/index.html
• Section in the renderers page explaining the similiarly named layers of the rendering system: https://docs.godotengine.org/en/latest/tutorials/rendering/renderers.html#renderers-rendering-drivers-and-renderingdevice
• Doesn't exist yet, but there is a desire for disambiguation (Clarify instancing #10472) in the instancing pages: https://docs.godotengine.org/en/latest/getting_started/step_by_step/instancing.html, https://docs.godotengine.org/en/latest/tutorials/scripting/nodes_and_scene_instances.html

[betalars]

In this case, a new short page in the Plugins section makes sense to me. If it's very short it could also exist in the index page itself.

Sounds good to me. I would also add a note linking to that page to the gdextenstion page then.

Would leave this issue open in case other use cases pop up until it has a section in the best practice doc?

Feel free to give it a better title.