Documentation and Websites Major Issues!

Godot version: 3.x and 2.x

OS/device including version: Not relevant for this issue.

Issue description: May I make a couple of suggestions that I feel (and I am sure many others that read this will too) would propel Godot to the stratosphere and most definitely put it on par or above with GameMaker Studio, Coco2d, Unity, Unreal, Construct, and many other professional and commercial game engines. I am sure many people do not currently feel like it is because of the lack of these 2 suggestions below:

#1. Hold off on all new features, bug fixes, and everything else until the ENTIRE documentation of Godot 3 is finished with complete descriptions, explanations, and samples. I can't count how many times I have had to find videos by different users just to do simple things that could have been MUCH easier explained in the documentation IF the documentation had been completely finished. Lots of times I can't even find videos for certain things mentioned in the documentation. This lacking of a GULLY FINISHED Godot documentation only hurts Godot in the present and the future.

#2. The Godot website, forums, and market place all are lacking in continuity of design. They look nothing alike at all. Even though they have links for each on the Community page, it does give the impression that these are not official Godot sites and not really part of Godot's website. I am sure many of people when they clicked the links and it went to those sites, they just pretty much just gave up on their problem and/or left Godot all together.

Now you may not think these are MAJOR ISSUES, but seriously, stop and really, really think about what I am saying. Look at it from a complete beginner's point of view and/or someone who has used Godot not very much at all. I am sure you will then see just how important these 2 suggestions really are.

Please? Thank You!

Steps to reproduce: Just look at the documentation and those web sites.

Minimal reproduction project: Just look at the documentation and those web sites.

Obviously they are extremely important. But this is still a GOOD problem to have. ;) to sum up: godot improoves in such a fast pace so that docs and video tuts struggle to keep up. Of course that is a huge issue especially for beginners. But it is also the only way godot could have become the engine it is nowadays. Stopp to implement features would have hurt godot in the past in also would hurt it now. It's just a strange proposal for an open source project to ask stop adding new features if ppl want to work on them.

This is just the way it is with open source. There are a ton of amazing ppl who write docs. And if there are more ppl needed, there needs to be an incentive. It would be amazing if the Godot Patreon for example would have even more supporters so that ppl can get paid for documenting. (I'm generally advocating a open source culture where supporting with money is more common. almost like tips in a restaurant)

I still totally agree that any work on documentation is worth A LOT. So thank you for making bringing up the topic.

I hardly disagree with asking ppl to stop adding features, AND BUG FIXES. Fist this is totally not how open source works. If I want to propose an idea/ feature I should be allowed to. If everybody hates it, fine, but everyone can work on whatever he wants. But your post already inspired me for example to maybe put some hours in it. It's just impossible to actually force it. Second the added features is what makes godot even be competitive. This is exactly how it should be.

Hold off on all new features, bug fixes, and everything else until the ENTIRE documentation of Godot 3 is finished with complete descriptions, explanations, and samples

I wouldn't prefer having a buggier, less capable engine in favor for complete documentation. While I agree that the docs is important, it should not be in a way of engine development. Open source softwares get features fast and it is difficult to keep the docs up to date. Also, users already have various ways of asking for help from the community. Discord, IRC, Reddit, Q&A, Facebook Group etc.

I was a beginner once too. The docs has improved a lot, and is more complete since 2.1. It should not be too hard to follow the official tutorial. At least that's the point of having a tutorial. (If some parts are difficult to understand, please specify it so it could be improved. Preferably in https://github.com/godotengine/godot-docs/. Saying the whole docs needs improvement is not that helpful.)

A lot of users really like the documentation, so instead of complaining about something more general, I suggest you just open an issue here:

https://github.com/godotengine/godot-docs/issues

Complaining about what you personally had difficulty with, being specific about it.

To think that if we stop accepting PRs here in favor of PRs to documentation would improve the docs is a fallacy. If we tell everyone to only work on the docs, people will simply go away. We're not entitled to tell what people should do in their free time. Most contributors that could fix a bug don't feel confident to write new documentation, especially those who are not native English speakers.

When I started using Godot, before 2.0 was out, the documentation was awful. Most of the API classes and functions were undocumented It used the GitHub wiki, so we couldn't even search for stuff, nor could the community edit it to improve it. It has come a long way since then. Now most of the API has documentation, especially the more high-level stuff (which is mostly used). And the tutorials are much more useful and cover more ground.

There's no reason to believe that the documentation won't get better if we don't focus 100% of the time on it. There are many regular contributors to the docs, including people doing revision and organization. It will only get better.

Eventually Godot will settle and won't have more major features to add, then it'll be a great time to fill in the blanks. Otherwise even if we fill the whole doc now it will have to be mostly thrown away in the next version. Godot 3.0 was a huge change and 3.1 will be quite big as well, especially in terms of interface (new Inspector, new animation tools), so focusing on 3.0 docs, means rewriting some chunks for 3.1.

I'm not saying we should ignore the documentation, only that it can keep growing on its own pace, no need to drop everything else in favor of it.

About the second point, we could make a new face to the asset library and the QA website, but it's not a dire situation. You can open issues on https://github.com/godotengine/godot-website and https://github.com/godotengine/godot-asset-library about this.

Just to note, most FOSS projects have their documentation done by the community, not the developers (the developer's job is to accept proposed changes from users).

I especially wouldn't like to see bugfixes halted until the docs. are complete (look at all of the Unity and Unreal forum threads talking about how buggy those engines are, Godot can make headway simply by being an engine where the vast majority of things just work).

A lot of users really like the documentation (...)

like me. i :heart: godot docs and im glancing through it often.

On the other hand, its true that most of people like to code fast, skiping comments and explanations on how something work and not documenting things because we keep everything in our minds. This way we code faster and quickly move forward to see how it works, (yey) but then most of us should be experienced to know that later it will end up veeeeery deadly.

Undocumented code without comments after enought time, turns unmaintanable even for its own author. Additionaly, it virtually does not exists since almost no one know that its there except fiew who made it or seen it merged. Its a waste to not share with world news about new shiny things that lurks within engine and on which someone spent alot of time and effort.

It could be good if feature author at least could add his feature to table of contents in docs, and write even just fiew short words and many TODO examples should be here, TODO whatever should be here and it might be enought to just give community sign that something like that exsists and should have its attention.

If theres a road leading somewhere, some people might find it interesting to explore it and share what great treasures they found there, by completing documentation with more details / examples ect. Just leave feature title in table of contents and fiew small TODO, TODO, TODO in docs for people to know that it exists, ... else it will sink in oblivion.

That could be a waste since godot 3.x is allready full of outstanding features... that are... secret.

Maybe it is just me, I don't know, but I get the feeling that everyone here thinks I am putting Godot down and that is just farther from the truth. I love Godot, I really do! I am not really complaining here, I am just making suggestions that I truly believe will improve Godot overall.

I can truly understand you all not wanting to hold off on new features and bug fixes and the like, these are great things that make any engine good and worthwhile. But just for a second see this, you can have all the new features and bug fixes you want, but if there is no really good documentation that fully explains what they are, how to use them, and demonstrates each , how useful are those new features if you can't figure out how to use them, seriously!?

I understand that Godot is rapidly changing, what was yesterday is not the same today. But if you don't have good documentation on what is today, then how are you suppose to use it tomorrow?

To just say that is how open source works is just completely blind. I have used and still continue to use a lot (and I do mean a lot) of open sourced software, and while there may be some with so-so or decent or bad or even no documentation, this is not the normal. I would venture to say MOST open source software HAS VERY GOOD good documentation, with great explanations and great examples.

Yes I do understand, you don't want to hold off on new features and bug fixes, so don't. As you said, people will work on what they want, when they want, and how they want. But that doesn't mean you have to accept their new features and bug fixes without full, proper documentation for each NEW feature and bug fix, BEFORE it is added to Godot! This way the documentation will MOST DEFINITELY improve as well as Godot its self.

Once again I just want to say, I love Godot and I am not putting it down or complaining about it, I am only suggesting how it can be made much, much, much better! For Everyone!!!

I have to agree that the documentation does need some work, but it shouldn't be at the expense of 3.1 having a much longer development time. I've seen many, many things in the docs that don't have a description, but more often than not they're somewhat self-explanatory, or are things I'm probably not going to need. And if someone does need an explanation on it, that's what things like the project's Discord or even the Q&A website are for.

I understand that Godot is rapidly changing, what was yesterday is not the same today. But if you don't have good documentation on what is today, then how are you suppose to use it tomorrow?

I don't agree with this idea that the documentation we have now is bad, though. Of course, it could really use some improvements (several pages in the docs haven't really been maintained), but I don't think it's at that unusable level yet.

Yes I do understand, you don't want to hold off on new features and bug fixes, so don't. As you said, people will work on what they want, when they want, and how they want. But that doesn't mean you have to accept their new features and bug fixes without full, proper documentation for each NEW feature and bug fix, BEFORE it is added to Godot! This way the documentation will MOST DEFINITELY improve as well as Godot its self.

Disagree with this idea. I think that would push people away from wanting to add new features, as odd as that might sound. Not everyone really considers themselves capable of writing some good documentation, myself included (I'd of contributed loads to the documentation had I not felt I wasn't capable of writing well), so I feel that requiring full documentation of added features will just turn people off from contributing. While it certainly isn't a bad idea to ask for some basic documentation, it's not something I feel we should expect from every PR, whether new feature or otherwise.

I imagine that when 3.1 is about to hit, though, maybe there'll be some more contributions to the docs? Or perhaps there could be more docs sprints, since those got at least a few pages updated every time one happened.

Also, I have a suggestion for you. If the documentation is so lacking to you, the website lacking in continuity to you, perhaps you could help improve it? I don't mean to sound rude, but it feels like the time spent complaining could have been spent improving things.

http://docs.godotengine.org/en/latest/community/contributing/index.html https://github.com/godotengine/godot/tree/master/doc/classes https://github.com/godotengine/godot-docs https://github.com/godotengine/godot-website

Sorry. You still haven't show me what part of the docs that's confusing to you.

I will tell you what exactly is wrong with your proposal:

May I make a couple of suggestions that I feel (and I am sure many others that read this will too) would propel Godot to the stratosphere and most definitely put it on par or above with [...]

This is just what you believe. These 2 suggestions are simply not enough to make Godot "on par or above" other engines. I could make an "engine" with very well described int main(int argc, char **argv) that you can understand that the first glance, but if that's the only function I have, is it on par with Unity?

Hold off on all new features, bug fixes, and everything else until the ENTIRE documentation of Godot 3 is finished

Like 100% of it? Imagine it happened. We would have 1,000+ PR on backlog. Merging it would be nightmare and rendering most of the docs useless/inaccurate. That would have meant the docs is not "finished." We would have to stop everything to finish the docs again. etc. Expect Godot 3.1 to come in 2025 at best.

I can't count how many times I have had to find videos by different users just to do simple things that could have been MUCH easier explained in the documentation IF the documentation had been completely finished. Lots of times I can't even find videos for certain things mentioned in the documentation.

You have the community at your expense. Use it to your advantage.

When I started, there was virtually NO videos on Godot Engine, let alone what I specifically want to learn. The community wasn't this big either. What did I do? I re-read the tutorial several times until I know the basics of it. (most of what you need to know is in the tutorial. you usually don't use what's not mentioned often.) I did "Trial and error" in the editor. Godot makes this very easy with scene system. Try everything you want to know.

I understand we learn best from different methods but we're sure our resources work for the majority of people. You can't just disregard them and say that we need to do something "better." At least tell us the exact part you find confusing.

(I'll skip the part about website. The design can be improved, but it serves purposes for now and is not a priority.)

you can have all the new features and bug fixes you want, but if there is no really good documentation that fully explains what they are, how to use them, and demonstrates each , how useful are those new features if you can't figure out how to use them, seriously!?

This is where I'd ask the community to help, search the blog post on the new feature, and/or look up the relevant part in the source code. It's not impossible.

But if you don't have good documentation on what is today, then how are you suppose to use it tomorrow?

In my opinion, what we have is pretty good. Because you haven't tell me what's wrong with it, I can't see it.

I would venture to say MOST open source software HAS VERY GOOD good documentation, with great explanations and great examples.

Link me to them please. It would be nice to know how they manage to do it. But to be able to do the same, they must have similar constraints. (have to implement large amount of features in short amount of time. etc.)

Yes I do understand, you don't want to hold off on new features and bug fixes, so don't. As you said, people will work on what they want, when they want, and how they want.

then why did you say...

But that doesn't mean you have to accept their new features

... Isn't this the same as "holding off on new features" for ones without docs update?

and bug fixes without full, proper documentation for each NEW feature and bug fix, BEFORE it is added to Godot! This way the documentation will MOST DEFINITELY improve as well as Godot its self.

I hope we agree that fixing the engine bugs on user end is harder than our end. That's why we have to merge bugfix so that users affected by it don't have to fix it themselves, while something like "not understanding how things work in the engine" can be solved easily by resorting to the community and/or source code.

We're currently holding off features that aren't part of the roadmap for some time. It has several cons.

By the time it's ready to be reviewed, it's outdated.
The contributor stopped working on it. (It's abandoned.)
It can leads to misunderstanding between the maintainers and the contributor. Something like "I wouldn't have worked on it if you told me first that it wouldn't get merged. Why didn't you tell me?"

Etc. That's why we try to discuss and merge it before it gets too old. Also, what we merge is what the community wants and we agree that it brings a smoother workflow. I'm not certain that stopping the merge would be justified.

We already enforce adding docs entry for new methods from contributors. Most of them gladly do it, but wouldn't you agree that "we're not gonna merge this because you don't provide docs" too aggressive? Several useful functions might not end up in the engine if we're too strict with the policy.

Also I'd respect reduz as he's one of the project founders. We're basically using what he made. I think it's not cool to have him describe everything he did just so we can understand it.

I am only suggesting how it can be made much, much, much better! For Everyone!!!

Not for me at least. It's already good enough. This assumption doesn't make it better. Now I doubt that the whole proposal is based on your assumptions and it might not work like you expected.

This is how it is. You can make suggestions. You can tell us what's wrong and we'll discuss on how to solve it. But NOT tell us to stop everything we're doing and do something else instead. I do what I do and feel like doing. It's not worth it and it's not going to happen.

I know that you love Godot. Most of us do. Loving is not enough. Also, doing what you're doing right now is not enough either. If you're not ready to contribute, at least tell us what part exactly that has issues. Maybe if you list methods with uncomplete docs, I could explain them better. (if I'm not too busy)

In conclusion:

I don't know what to do with this issue. It's too vague.
Stopping everything won't magically create a better docs and make Godot better. At least in the near future.
In this situation, the issue is too vague to justify "stopping everything." It is an illogical solution.

TLDR: tell me what exactly wrong with the docs/what you want to do but can't because the docs is incomplete.

Edit: Apologize for the wall of text, also if I come off as aggressive. It's not my intention. According to the FAQ we are supposed to find a solution that works for both of us. The discussion won't go anywhere if you insist that your solution is the only way without providing proofs.

godotengine / godot

Documentation and Websites Major Issues! #20949