Godot-proposals: public comments in the documentation

[doradoro]

Describe the project you are working on:

simple 2d game

Describe the problem or limitation you are having in your project:

lack of documentation inside and outside of the godot editor

Describe the feature / enhancement and how it helps to overcome the problem or limitation:

Let the people create comments, proposals or improve the documentation like the php manual "notes"

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams:

the "user contributed notes" section
https://www.php.net/manual/es/function.stripslashes.php

If this enhancement will not be used often, can it be worked around with a few lines of script?:

i don't know how the documentation works

Is there a reason why this should be core and not an add-on in the asset library?:

Its a basic feature

[clayjohn]

Godot is an open source project and so every part of it (including the documentation) is user contributed.

The docs are hosted in a public repository which anyone can access and add it.

In addition, the online documentation has detailed tutorials on how to contribute

If you have a specific node or function in mind, please create an issue in the godot-docs repo to let other contributors know that a given class or function is missing documentation.

[doradoro]

You did not understood the proposal...

[clayjohn]

We'll, feel free to explain yourself further. All you have said is

Let the people create comments, proposals or improve the documentation like the php manual "notes"

And since that is already possible I have closed the proposal.

Also, while you are working on it. Please see the rules. Note that the entire template needs to be filled out for your proposal to be considered.

[doradoro]

No, it's not possible in the godot editor and either in the online documentation. You can't contribute from there or create different point of views about the way to use the things.

I filled it entirely having in count that is not appropriate for the kind of proposal.

[clayjohn]

I see. It sounds like you are asking for a way to modify existing documentation from within the engine?

If so, please edit your original proposal and make that clear. And please fill in all the questions. If you do so, I can reopen the proposal. :)

[doradoro]

The proposal been perfectly clear. Delete it. Bye

[IINinja]

That is good idea, people users of godot to leave comment and examples of code like in SoloLearn app for mobile phone for learning programming languge....that is the best practice to learn and you view this code in diferent examples.....that is good practice....

[Feniks-Gaming]

Lol @reduz on twitter "open the proposal so we can discuss things" . 2 min later godot core contributor "I'm closing it without discussion see ya"...

[Calinou]

@Feniks-Gaming There was an issue about this in the Godot documentation repository (which is a more suited place for this kind of proposal). However, I closed it as there was seemingly little interest in actually implementing it.

Not to mention documentation feedback/note systems come with their own downsides, such as poor SEO. This means you can't easily find results in search engines like you could with questions asked on Reddit or Stack Overflow.

[Feniks-Gaming]

This is a place reduz link this poor guy to open a proposal.

Not to mention documentation feedback/note systems come with their own downsides, such as poor SEO. This means you can't easily find results in search engines like you could with questions asked on Reddit or Stack Overflow.

I don't disagree here I don't think this proposal is without a flaws but it pisses me off that Reduz on twitter invites people to discussion to then see those people having discussion terminated in a span of 10 min by @clayjohn.

What is a point of then saying "We are open to discussion", when we are really not. At least lets have this discussion discuss pros and cones and make decision there closing issues because we disagree with it without any discussion or feedback from community is a perfect route for creating echo chamber.

[reduz]

I do believe having a feedback/note system or a comment system in the documentation would definitely be a good idea, so our community could complain in a way with proper context (instead of just complaining and saying doc sucks) and/or help each other over there.

That said, just asking for the feature will lead nowhere, I think a more technical or realistic proposal (on how this could be implemented) would be better.

We use ReadTheDocs because there isn't really anything much better documentation wise and it has a lot of plugins, but if we could embed some sort of external comment system (so we don't have to manage accounts and registration), then that would be great.

[doradoro]

Of course i'm not going to implement it. I can't. I should be able to understand the basics of Godot before start to think in changing the Engine, the website or whatever other thing by myself...

This is a proposals system, not a DIY system and the template is not suitable for proposals.

There is no other place to solve the basics. I'm not a contributor. I'm an user.

You should decide WHERE people must do the things before blame them of not knowing where to do the things. I tried to help to translate the documentation because is wrong and some other person told me that here was not the place. WHERE is the place? WHERE is the place of everything?

forum? discord? IRC? Q&A? the editor? the web? WHERE

That is exactly what i'm saying. There is no "WHERE" to solve the problems.

It's not my-our fault, it's the system flaws. It must to guide the people automatically, not insulting them and their free collaboration = free work because you doesn't offer WHERE to do the things.

WHERE can i know how Godot works? No, the documentation doesn't solve that issue. WHERE?

I offered an exact example of how to solve the problem. What more i must to do? code it by myself?

[Tiagoesc]

The SEO downside isn't too bad when you think about how users would use it: they will go to the page they want to know about, no searches needed.
Btw @Calinou, the "issue" about this you linked is not actually the same "issue". Maybe everyone should check the PHP link provided as example?

[reduz]

@doradoro I agree with you, we have no way to know when the user had a problem with the documentation. They may go and open an issue, post in QA or something, but we still can' t link this to the piece of documentation that failed to convey the information required in order to improve it.

This is why a system like this is very needed, but our resources to implement something like this are limited (our contributors are not into webdev and much less are into hacking RTD).

[doradoro]

I know webdev but i doesnt know ReadTheDocs internals (yet) or how godot implement it... It should be easy to link the Q&A system with the RTD one but i doesnt know how that should affect the Editor... I suppose that uses an API instead parsing the web directly.

[Calinou]

@doradoro The editor help is generated fully offline from a set of XML files. We'd rather have it keep working offline, so we'd prefer not making it contact an API every time someone is loading a page in the editor help.

[doradoro]

I think that it should be better to have the online version only with the option of download it manually for the few people who should use it offline, RTD have that feature.

There is no ID in the XML files but it should be "faked" using the inherits and name vars and create automatic "main questions" to hold the user contributions.

Using Javascript to load the Q&A in the online manual can avoid the "SEO problems" but in the php manual experience it seems useful to add those comments to the manual pages.

Or you can create unique links and put them everywhere.

[reduz]

@doradoro Actually linking the QA dynamically (like an iframe?) sounds like it could be interesting. This is a very good idea I think.

QA has tags, and docs have unique tags for each page already to identify this tag, so we could assume every page has a tag. As an example, we could put an iframe to the QA listing all the questions with the tag of the page (and a button to open a new question using this tag as a template).

It would also solve the SEO problem @Calinou is worried about.

More practical example of how I would make it work, you can see this page:

https://docs.godotengine.org/en/latest/tutorials/physics/using_kinematic_body_2d.html

So in the end you would see something like:

(please use your imagination, the questions in the mock-up are unrelated to the page), all it would do is show the questions related to the tag of this specific page, which is something like "doc_page_using_kinematicbody_2d".

The Ask Question button will take you to the QA to open a question with a template and the tag added "doc_page_using_kinematicbody_2d".

Then, every page can have its own list of related questions, but you can still browse them from the QA site and they will appear in Google.

How doable this might be?

[doradoro]

Google parses javascript actually so the seo thing should need more workaround like using the < ! --googleoff: all -- > (and others) comments before printing the iframes

i saw something about templates in the Q&A script so we should create an "iframe template" with that big button bellow or put it in the DTM template below the iframe

[xix-xeaon]

@Feniks-Gaming I've _felt_ on several occasions reading through issues that many of the core developers only care about closing the issue as fast as possible - as if that automatically solves the problem.

I've _felt_ like they're looking for the slightest excuse to close, preferring to say "it's intentional" instead of "yeah, it could be better" and often completely dismissing features which absolutely should be core saying "you can make it yourself". Or the announcement about closing all the PRs which I'd say is an absolutely awesome way of effectively losing work and turning people off the idea of contributing.

I think the _truth_ is that the core developers are simply overwhelmed. A game engine is a large endeavor and there are very few core developers having to shoulder that burden. They're happy to accept well done PRs and even help people improve them - they just can't take on more work for themselves and that's what unfortunately leads to the dismissive attitude.

I do think something needs to be done about that though. Reading this issue makes it clear how frustrating it feels when someone tried to help only to be completely dismissed.

On this issue I remember working with PHP some 15 years ago and those user comments were almost always at least as useful as the actual documentation, perhaps more. The difference is that official documentation is just that - official.

It's easy to write a comment. You don't need to create a PR, or even figure out what it is. You don't need any "bureaucracy" of having it reviewed and accepted. It's also a completely different thing mentally to "just write a comment" instead of "contributing to the official documentation" - things like fear of rejection and a whole bunch of other psychology applies. And Godot don't need to worry about "should this be part of the doc or not".

I remember the user comments for PHP being full of tiny gotchas and code examples that made life so much easier and in practice could never, perhaps even should never, end up in the official part of the documentation.

I think user comments in the doc would also be a great addition as a way of "feeling the pulse" of the users. Like what's missing from the doc, how classes are actually being used and what features are missing.

The user comments could be collected once a week in a file added to the latest release / maybe have a button in the editor to download the latest such file. It might have frequent significant changes in the beginning but should stabilize over time. I don't think you need to be able to submit comments from the editor, just a link in the editor doc to the web doc should be fine.

Also, I do believe SEO is a non-issue.

[Feniks-Gaming]

Could we maybe reopen this proposal since discussion is ongoing so others can see it?

[groud]

Could we maybe reopen this proposal since discussion is ongoing so others can see it?

I might reopen the proposal if the first comment is edited with detailed explanations about what could this feature looks like. We intend to keep the quality of the proposal in this repo high enough, one line of description is not enough for a proposal to be considered as valid.

[reduz]

IF you guys are ok, I can open a new proposal actually using my mock-up and more specifically about embedding QA into the documentation

[MagellanicGames]

The core idea is certainly a good one. Maybe open another similar proposal?
edit: derp, too slow

[doradoro]

Yeap it should be great because i'm not very polite

[reduz]

done

[ShlomiRex]

Of course i'm not going to implement it. I can't. I should be able to understand the basics of Godot before start to think in changing the Engine, the website or whatever other thing by myself...

This is a proposals system, not a DIY system and the template is not suitable for proposals.

There is no other place to solve the basics. I'm not a contributor. I'm an user.

You should decide WHERE people must do the things before blame them of not knowing where to do the things. I tried to help to translate the documentation because is wrong and some other person told me that here was not the place. WHERE is the place? WHERE is the place of everything?

forum? discord? IRC? Q&A? the editor? the web? WHERE

That is exactly what i'm saying. There is no "WHERE" to solve the problems.

It's not my-our fault, it's the system flaws. It must to guide the people automatically, not insulting them and their free collaboration = free work because you doesn't offer WHERE to do the things.

WHERE can i know how Godot works? No, the documentation doesn't solve that issue. WHERE?

I offered an exact example of how to solve the problem. What more i must to do? code it by myself?

I had exactly this problem when I first started
it turns out you just search in the code the things you need
Ill give you an example
I wanted to find where in the code does the project manager "Browse" button is pressed
took me 3 days
eventually it is file_dialog.cpp
I put tons of breakpoints
but eventually I used call stack and it helped me a lot