Godot-proposals: Embed QA into documentation pages

[reduz]

Describe the project you are working on:

Godot

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

There is a disconnect between users not understanding the documentation and them asking for help in the QA or other social networks. Because of this, we fail to see which piece of documentation was the one not providing enough insight, making it harder to fix it.

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

Each documentation page already has a unique tag, which is used to describe it within ReadTheDocs. We can use it to generate a unique tag on the QA.

The QA can be embedded at the bottom of the documentation page linking all the issues that contain its own tag. This way, users can see a list of questions directly related to the page.

Additionally, an "Add Question" button can be added to the bottom which would lead to the QA open issue template containing the tag.

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

(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". I suppose in order to work more smoothly, the button could be greyed out and show "Log in (with link) to QA to ask a question for this page" or something like this.

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.

I know there are more advanced systems out there for these kind of things, but I believe this is by far the best we can do with our resources.

[Feniks-Gaming]

This is great compromise between users being able to ask for clarification without a hassle of them making a new issue on github. I think it will help doc writers to see what is missing and will give good direction those with better githubfoo to just incorporate some of good answers into documentation itself.

Many times I wanted to ask quick clarification question without feeling like I need to create whole issue on gitgub

[Lknechtli]

I think you'd want to link questions/answers to a specific version of the documentation, perhaps as an addition tag. Give users the option to view questions and answers for all versions but default to showing just the current version and have a visible tag showing the version. That way it's clear when the content that questions or answers refer to may have changed or been fixed.

[AdamSGit]

I think this is a good idea. I would prefer user's notes rather than QA directly embedded in doc. Take PHP for example, I find more often the answer I look for in the user's note than in the doc in itself when it come to specific stuff.

The idea of choosing the version you target with notes or QA is important, of course.

[doradoro]

Here we goes... I will take this page as an example:

https://docs.godotengine.org/en/3.2/getting_started/scripting/gdscript/gdscript_basics.html

Way to achieve:

• Modify the RTD template adding an iframe with an unique ID
• The iframe will have a predefined url using the unique ID
• Modify the Q&A template to add a "clean" look option (without UX, menus, footer) and the "Ask question" button (to avoid appears below a big white box)
• Modify the Q&A form template (to add tags by url)
• Modify the Q&A Categories to define Godot versions
• Remove bad comments and spam from time to time

Ex:

Unique ID: getting_started.scripting.gdscript.gdscript_basics
url: https://godotengine.org/qa/tag/getting_started.scripting.gdscript.gdscript_basics
iframe:

The iframe should have the predefined width of 100% and a standard height plus scrollbars (achieve the exact size should be cross site scripting) so it will "hide" the worse voted comments. The comments would be ordered by votes. I don't think we should split language or versions. PHP manual does not do... And the questions would have the version included using the Categories.

About the "seo thing" i don't consider a back-shot to publish the comments if we filter spam ones... but you can hide it using googleoff comment tags

The "ask question" button should work using _GET vars and filtered like this to avoid XSS attacks:

https://godotengine.org/qa/ask?tag=getting_started.scripting.gdscript.gdscript_basics

$tag = filter_input(INPUT_GET, 'tag', FILTER_SANITIZE_FULL_SPECIAL_CHARS);

[Xrayez]

Talking about tags: godotengine/godot#29286.

[golddotasksquestions]

The GDScrips basics page is a good example where I don't see comment's on the bottom working very well.
This page is so massive and has so much content, the comments would be about everything and it would be had to find or see any useful information.

I made an issue about splitting it up a while ago, but as it is with all docs issues, they hardly ever get enough attention to even have a discussion.

I would really love a side column with click-able link cards that would send me directly to the right comment. I would also like to just click next to a line to "make a comment here". The comment would be at the bottom of the page, but the card would show up right there where I clicked to make a new comment:

If comments had "flavors" like Reddit posts, bugs could be immediately be picked out, and so would be really helpful additional info some user would post.

Ideally issue flavored comment cards like "Clarification needed" or "Bug" should be automatically removed from the coll um once fixed or a solution was found. So that there would be more "Tips & Tricks" card links than issues.
Regular comments that are not about any particular line can still be made at the bottom of the page and the whole column should be able to be hidden for those who find it irritating.

[doradoro]

Why everyone here thinks we all are godot core engine pro contributors experts in c++ instead normal users trying to learn the basics? We need to split core engine function proposals from this kind of UX and user-thing questions = basic engine learning.

I think that would be great to have some kind of pool like in uservoice CRMs...
https://www.uservoice.com/product/

And then, passed that filter, start this github thing with forced sketches...

[golddotasksquestions]

@doradoro I agree with you. I'm "just a user" myself.
However if the documentation has a bug, this bug can snowball into an avalanche of buggy projects, buggy tutorials, general misunderstandings and false assumptions. Users that get nowhere with their project because they trust the docs. Imho those should be fixed asap, before everything else, before any engine bugs.

Right now the only means to report them are via the Github issue system. But https://github.com/godotengine/godot-docs/issues is even less frequented than https://github.com/godotengine/godot/issues or https://github.com/godotengine/godot-proposals.

The more we can streamline the process from "Seeing a bug in the docs" -> "making it known to others" - > "fixing it", the faster they go away, the less users time and brainpower is wasted on issues that don't even exist. If the price is a annoying red button next to false information, I can accept that. Even if the documentation is not immediately fixed, that red rectangle would be a valuable info for me as regular user.

[doradoro]

Oh fuck i'm NOT talking about bugs. The entire documentation its a bug itself and there is not a "bug reporting" button anywhere, only a "edit this page" and we do NOT know how to fix the problems!

You all suck the spirit and joy of using godot like vampires! You all stop "contributing" your cancer to the project! Are you all paid by Unity to destroy godot? This system is aids!

[pyacier]

The documentation is translated in several languages, how is it going to work with the QA ?

If all the translations have the same QA, then the majority of them will be written in English. If a good precision is added by a QA in English, a non-English reader will not have access to it.

I’m aware that it’s a fact that most of the community will exchange in English, my concern is the risk of being lax with the content of the documentation because the precision is added by the QA.

Apart from that concern this seem to be a good idea.

[Lknechtli]

@pyacier I think the idea is that documenters would use the Q/A as a feedback system when trying to determine what parts of the documentation need to be improved.

We can't expect people to translate Q/A, but clarifications from answers should eventually make their way back into the documentation, and from there, be translated.

[IINinja]

That is the Bingo!!!!

[CastilloDel]

The HTML for the doc pages needs to be modified, but in the godot-docs GitHub only the reST is stored because the HTML is built by Sphinx. Could this be done by editing the Sphinx theme?