Godot: Suggestion about Godot documentation to improve usability.

[zaksnet]

1) All Methods could be in a tree format ( foldable ).
2) All Methods could have optional "examples" underneath them which will also be foldable. And a contribute button where users can contribute examples.
3) Search by tags like: #Movement, #Fly, #Rotate, #Die. Examples:

Movement:

This could return anything related to moving an object.

Movement, #Physics

This will return anything related to moving an object AND also using the physics engine.

Die

This could return anything related to deleting an instance from the game ( I still don't know how to do that!)

To expand my noob perspective so you can better understand what i mean,i have a vision of a game that will:

• Have a character that will be moving and jumping around on platforms. I have no idea how to do that, or what to search in order to do that. So i'd have to spend hours watching videos or reading articles. BUT fundamentally i know that i want to #move and #jump so if i could search for those 2 terms and possibly see some examples i could probably figure it out.
• Same with #Die, i know that my play has to die once he touches something. So die could return functions that restart the scene possibly.

I will be expanding that as i go but the idea is that users will be able to add tags also so it wont be too much of work to the main devs

[KoBeWi]

I agree that in-editor docs could be improved, I made a similar issue about that: #27456

But I don't see how hashtags would be useful. #Die tag would be literally in one place - the queue_free() method. This doesn't really fit into class reference, but might be useful for general docs, in which case you could suggest that in the dedicated repository: https://github.com/godotengine/godot-docs

[zaksnet]

"But I don't see how hashtags would be useful. #Die tag would be literally in one place - the queue_free()"
It could also return functions that restart the level or reset the scene or anything else. But you are missing the point, even if it returned just 1 function, people who are not familiar to game development in particular usually don't know how to proceed with their task. They know the goal but not the means to achieve it. This could help by alot building the logic. Having it on the online docs is fine defies the purpose I just described. Leaving the engine and searching the web is unpractical and most of the times distracting

[slapin]

Well, I think all docs should be converted to comic books for anybody to actually read them. People are illiterate these days and can't consume information in text form at all. Linking them to docs is always useless.

[Xrayez]

I would always support creating a documentation system that appeals to visual part in our thinking process, this is how our brains work in the first place. One might not realize that, but those words end up as actual images in our heads 90% of the time. Somehow people of science (possibly with plenty of experience) tend to neglect this internal process as it becomes automatic and invisible to them, so they become reluctant to express strict ideas in interactive form, which is essentially what we aim for anyway, especially in the field of game development.

It would perfectly integrate with formal descriptions as well, so +1 for the tag system. It could also be broken down into topics instead, Python has something similar in terms of built-in documentation.

[Calinou]

Tags could also be used to improve the help search dialog. Members could appear in the search if at least one of their tags is present as a search term (in addition to the current search system). This could be useful if the member's name has several synonyms, so that people don't accidentally miss documentation they were looking for. To give a semi-contrived example, Camera.far could have the tags zfar, far_clip and farclip so that it'd appear in the results if you type any of those terms (currently, it doesn't).

However, I'm not sure if generic topics are that useful, which is why I think more focused "tags" (which might as well be considered "aliases") make more sense in this context.

[zaksnet]

I was talking about this Search Help:

It is the first thing people should be referring to when they want to find out something but if they don't the API or the names of the classes or the names of the functions they might miss out things as @Calinou stated. You can call them alias, hashtags or keywords, it doesn't matter. My point is that most of the times you have to search the web while the build in docs should have been enough.

[slapin]

Adding some indexing tool to the doc, or geenrate doc index at Godot build
time would be more healthy idea than adding piles of useless hashtags.
Because just adding hashtags without relation graph will not make doc
searches any easier.

On Thu, May 30, 2019 at 9:27 AM Zak Stam [e-mail] wrote:

I was talking about this Search Help:
[image: Image of Search help]
https://camo.githubusercontent.com/a97e94220473458c8a25fea8162e7046bb737045/68747470733a2f2f692e7974696d672e636f6d2f76692f4b463069784d786d5739382f6d617872657364656661756c742e6a7067
It is the first thing people should be referring to when they want to find
out something but if they don't the API or the names of the classes or the
names of the functions they might miss out things as @Calinou
https://github.com/Calinou stated. You can call them alias, hashtags or
keywords, it doesn't matter. My point is that most of the times you have to
search the web while the build in docs should have been enough.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/godotengine/godot/issues/29286?email_source=notifications&email_token=AAABPU2A3VWYSJVJJIVIWKDPX5XUZA5CNFSM4HQODXGKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODWRPRUI#issuecomment-497219793,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAABPUYKRSTVM6HPXGJQBJTPX5XUZANCNFSM4HQODXGA
.

[Xrayez]

To me hashtags would be reminiscent to a complete graph (or star graph), so a simple doc tree wouldn't necessarily fulfill what @zaksnet suggests, so adding tag relationship might also be necessary. The tags wouldn't be visible by default, unless you want to see the hashtag cloud in a separate window to give more broad coverage of what the engine can do at higher level.

[slapin]

I think adding a small indexing tool at build time and small index search
tool in editor would solve problems without heaps of manual work.
There are many tools out there which can help with this. Adding keywords
myght help when you have the indexer running, but relying on
keywords only will lead nowhere. Also it might be that you will not need
too many of keywords, if at all, for good searches.

On Thu, May 30, 2019 at 12:30 PM Andrii Doroshenko [e-mail]
wrote:

To me hashtags would be reminiscent to a complete graph (or star graph),
so a simple doc tree wouldn't necessarily fulfill what @zaksnet
https://github.com/zaksnet suggests, so adding tag relationship might
also be necessary. The tags wouldn't be visible by default, unless you want
to see the hashtag cloud in a separate window to give more broad coverage
of what the engine can do at higher level.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/godotengine/godot/issues/29286?email_source=notifications&email_token=AAABPUYQQM6V3GWTNA7IUUDPX6NBXA5CNFSM4HQODXGKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODWR3FKI#issuecomment-497267369,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAABPUYZF224ZQCDQI42ERTPX6NBXANCNFSM4HQODXGA
.

[Ranoller]

Docs in godot are great... there are one of this features that make godot editor better than unity editor... but it´s true that enhacements would be done. Ability to open them in other dock that script editor will be an improvement. Other improvement will be make the help in the richtextlabel of a doc directly with one bbcode call (richtextlabel.bbcode = bbcodetext) but actually i think it uses append bbcode to do that line by line and you can not get that bbcode to make a plugin and open the help in a separate dock (I try that, not doable)

[mindinsomnia]

Second Ranoller.

Godot's docs are pretty awesome and I love any software that comes with it's own detailed documentation included of all the functions and classes and such. Nothing makes software more immediately useful than that. No point having an API if no one knows how to use it.

But enhancements are always welcome!

One cool enhancement would be having a hover bubble appear when you hold your cursor over a function or something, that maybe shows a description of the arguments it takes, maybe even something that can be clicked on to go direct to the documentation for that function.

[Calinou]

@mindinsomnia Documentation hover bubbles are already being discussed in https://github.com/godotengine/godot/issues/27607 :slightly_smiling_face: