Godot: Comment system for documentation...

[Qws]

Hi, I'm new with Godot, and I love open-source. Godot is the best thing ever that happened for me as someone who is trying to make 2D games for the first time. At first I didn't liked GDscript, but after using it for few days I'm starting to enjoy it.

My biggest problem with GDscripting is the lack of useful information/details in the web documentation.

When I search for .scale() I wish the website documentation could give me more information than this:

void scale ( Vector2 ratio )
Apply the ‘ratio’ scale to the 2D node, according to its current scale value.

Maybe for you guys this is informative enough, but for me it isn't, and I also don't see the difference between scale() and set_scale().

I'd love to read other people's opinion/experience/examples about certain function/topics/tutorials. For now I'm just following Youtube tutorials till I eventually find a video where someone shows how to properly use Scale() function.

I've read that you guys don't like "solutions" from users. But this is a idea for a feature request.

I really wish to see comment section for each API/function in Godot, something similar as PHP's documentation, A "guestbook" where people can share their experience and example codes with a simple comment. Integrate it with an upvotes and downvotes system, just like PHP's documentation to get most useful comments at top, and least useful stays bottom.

That way it's very easier and less scarier for people to contribute and talk about certain functions of Godot scripting API. Instead of going through Youtube video tutorials and spamming Reddit with questions.

[bojidar-bg]

Well, right now, the documentation is still a bit sparse -- some classes don't even have a "brief description"!
It would actually be nicer if documentation was understandable fully -- without the need for PHP-like comments. Those comments would probably just hide the issue of the documentation being bad, not just being a bit hard to implement.

So, we should actually choose if we should really go with comments, which would make editor docs nearly useless (at least without internet connect), and would also be a pain to implement "properly", or if we should go with more extensive (and somehow nicer to contribute to) documentation, particularly one with code examples and stuff (as already partly discussed in https://github.com/godotengine/godot-docs/issues/133)

So, to sum up, here is a "visual" difference between the two ideas presented by me:

Idea 1 (comments)

class Node2D

… (many many many methods here)

Method set_scale(scale)

Sets the scale of the node to scale.
… (many many many methods here)

Comments

… Many many many comments here

@somenamehere - Keep in mind that set_scale sets the "final" scale of the node directly (the thing you would see in the inspector), while scale multiplies the new scale by the current scale (like saying you would like to have in 2x bigger than the _current_ size)

… Many many many comments here

Idea 2 (extensive (sometimes) documentation)

class Node2D

… (many many many methods here)

Method set_scale(scale)

Sets the scale of the node to scale.
Expand:

» Sets the scale factor of the node to some new scale. This makes the sized based on the initial size of the node, unlike scale(ratio) which would make the size based on the current size of the node
Code example:

extends Node2D
func example_scale():
  set_scale(Vector2(2, 2)) # Makes the Node2D twice bigger than initially
  set_scale(Vector2(6, 2)) # Makes the Node2D six times bigger on X and twice bigger on Y than initially
  set_scale(Vector2(1, 1)) # Resets the Node2D's size

… (many many many methods here)

[Zylann]

I like the second, Qt does that too and it's really useful to get started on any class (even if it feels verbose for experienced people). Not all methods need full examples, and if you need just a quick look the doc is already split in two sections (brief summary of class, then details)

[hubbyist]

Maybe a comments system backed online documentation can be used as an easy to access platform for seeing how the community understands and explains Godot to each other. Comments and examples on this system may eventually be promoted to be part of an official extended documentation. Additional file for each class can be supplied in an extended documentation folder composed of promoted examples and detailed explanation with Godot to prevent need for always being online. This can be a separate download like export templates as well.

I am a php developer, so I know that comments below each function documentation is very useful to find how to start with using that function and possible outcomes.

[bojidar-bg]

Do docs become better just by adding comments to them? If docs need additional clarification comments documenting them, what is the point of having docs at all? I guess just having a forum where a few commited contributors just make topics about every new method as it comes out would be about as useful...

Still, the core issue we are looking at here is that the docs aren't useful enough -- there are many methods that don't seem to do exactly what is needed, some are too similar to others, some don't do a thing because you forgot to call something else (e.g. the Tween class), others are just documented too vaguely. Well, there have been multiple solutions to this problem -- either have some people writing docs "full-time", put the community somehow in charge of it, or just forget it.

Having people work on improving the docs is a pretty good idea, and it has led to some pretty good results so far (~30% to 52% percent of methods and constants documented).

The other idea, having the community work on the docs, is a bit harder, since most people might want to help, but they need a very simple to start with interface to motivate them, rather than a 10-step process done in more than 30 minutes.

1. The simplest idea for this is to make a "comments" section, to workaround the misfeatures of the docs. Sadly, this usually leads to having information be spread over too much volume, and thus harder to find. Also, this still won't fix the core issue fully, as the docs still won't be as complete as possible. Finally, if we download the comments to have them offline, we would actually be workarounding something introduced by a workaround -- totally not what we want to do.
2. A harder, but _potentially_ better idea would be to make the docs easy to edit, and containing everything one might actually want to see or tell others about. This would include adding examples, long but obvious descriptions, more examples, and probably even translations. Also, this would include making a GUI (in godot?) for editing the docs more easily, as currently it is nearly a nightmare :smiley:.

Both of the last two solutions would probably include a slightly enhanced search system, so people can find the needed method faster.

(Yeah, my long 2¢)

[hubbyist]

Second option is a far better solution IMHO.

I was thinking about three stage documentation process when I think about collaboration backed documentation.

1. Get auto generated documentation from code
2. Add additional information like related functions, clarifications, examples by developers
3. Add best practices, known issues and troubleshooting, from community.

For 3.stage add a collaboration system (comments or co-editing) to documentation workflow. Then periodically cheery pick contributions which are good enough to enter documentation in 2.stage and delete the useless ones or move all to an archive. Repeat until documentation do not needs external contribuitons anymore (not 100% achievable may be, but worth trying :smile: ).

I think a manual forum will not match and automated system which is directly scanning code base for classes and related information to achieve this.

[bojidar-bg]

@hubbyist Well, to be fair, we already have stage one and part of stages 2 and 3.

What is left IMHO is:

1. Change the docs to have examples and long descriptions and stuff
   
   
   
   • This would be a _very_ good time to change the docs format and/or split them as per #3941
   
   
2. Update all documentation tools, especially the docstatus tool
3. Make a all-new editor for the docs
   
   
   
   • It might be done as a cli tool, or as a Godot game, or as a web tool (somehow)
   
   
4. Write docs, and tell the community how easy it is to write docs now

But, anyhow, I'm not sure if this should be closed as a dupe of https://github.com/godotengine/godot-docs/issues/133 and #3941 or if it should be retitled and probably linked into an all-new tracker. WDYT @godotengine/bugsquad ?

[kubecz3k]

@bojidar-bg I personally think this issue should not be closed, there are couple interesting propositions here, and in some way those are about different aspects of creating documentation. https://github.com/godotengine/godot-docs/issues/133 is simply about adding ability to separate function docs from class docs, while this one is more broad (and also have some propositions for https://github.com/godotengine/godot-docs/issues/133). I think we can just mention this issue (or concrete comment from this issue) at the beginning of the first post of https://github.com/godotengine/godot-docs/issues/133 What do you think?

[bojidar-bg]

@kubecz3k Sounds good.

[kubecz3k]

@bojidar-bg I'm not a member of @godotengine/documentation so probably you or @StraToN will need to make those changes :)

[Qws]

You guys realise that I also mean comments for official Godot tutorial pages?

Imagine if I want to share my own example project for this Godot tutorial: http://docs.godotengine.org/en/stable/tutorials/2d/cutout_animation.html

Is there a better place to share my own 2D skeleton example than beneath the tutorial itself? Sure I can post it somewhere in Reddit or Discord... but the person who needs it probably won't find it on Reddit or Discord chat.

Why is there rejection for comment system any way? In my opinion it's not that harmful at all. It makes the tutorials a tiny bit more interactive and more friendlier. People could talk about common (beginner) mistakes or tips, Something the documentation maintainer forgot, overlooked or perhaps thinks it's not worth it in official documentation.

You can have most advanced documentation, but it might still not be enough for some people. A great example is .NET documentation. Imo still less informative than PHP documentation...

The most important part of a comment system is the fact that it lowers the treshold for "noobs" (like me) to ask question about (a very) specific part of the documentation topic/tutorial.

[bojidar-bg]

@Qws Well, for asking questions there is the so-called QA site...

[hubbyist]

Some method to merge documentation and QA into a integrated system may solve lots of problems it seems. Problem is information in community is scattered into multiple channels IMHO. So a web interface to unite all these channels by preserving their respective functionality will be helpful I think.

[c-cesar]

Reading this thread I got the word "wiki" stuck in my mind.
If we want the community to write, comment, improve and ask questions in the documentation, the documentations should be in a wiki.
So, someone should run in the wiki marix and chose one.

[bojidar-bg]

@c-cesar We had wikies in the past, and they generally went underused and not very useful. Currently we are using ReadTheDocs, which means that you can edit/clone/etc. the documentation as you wish to in the godotengine/godot-docs repo.

But, the issue right now isn't so much about the tutorials/etc., but more about the class reference, which is currently a big blobby .xml file in this repo...

[StraToN]

@c-cesar As @bojidar-bg stated, we chose ReadTheDocs instead of wiki solutions for multiple reasons. First, it's easier for developers to write docs in files than in page-editors. Of course we are also aware that this solution is not newbie-friendly (as writers have to learn git and Sphinx syntax, no wysiwyg) but it is also much easier to maintain and in the long term produces better-quality documentation.

About the main topic, I personally dislike comments on documentation pages. Very useful information usually lies there, but most of time few people ever read down there and only refer to documentation. As a result, users drop their tips and tricks in the comments and "hurrah! job's done, I shared great stuff". But also as a result, documentation doesn't improve as no one writes docs with this new stuff. No one wants to refer to comments as a documentation source, especially when there are thousands of comments on a single page - take PHP documentation as a good example for this.

I believe that if someone has a good information and wants to share it, he'd then better write a new page and/or edit an existing page and add his knowledge. If he can't/doesn't want, then he may simply put and issue here so everyone can see it before one writer adds it to the doc pages. That's how it works.

[willnationsdev]

Randomly came across this. Isn't the only thing we need to do in order to close this issue the ability to add expandable regions into the makerst.py stuff for the XML documentation?

[Calinou]

Is this issue still relevant today? The documentation has been improved significantly since this issue was opened.

Support for sending documentation feedback from the web page is being tracked in https://github.com/godotengine/godot-docs/issues/323, but I also think it's less relevant now that we have a Request Docs button at the top of the script editor and editor help.

[clayjohn]

I agree. Adding the Request Docs button closes this proposal.