Godot: Documentation debt will explode

[Omicron666]

Godot version:
X.x.x

OS/device including version:
All

Issue description:
Because with even more contributors and contributions, the documentation debt will grow even more at uncontrolled pace.
Shouldn't developer document (for automatic doc generation) their own additions and features ?

Steps to reproduce:
Merge more undocumented PR for new features or functions. Like all of them: https://github.com/godotengine/godot/pulls?q=is%3Apr+is%3Aopen+label%3A%22feature+proposal%22

Three solutions I suggest are:

• getting at least awareness of new contributors (and current ones ?) especially for auto-generated documentation that can't be done directly in godot-docs, by adding documentation requirement/incitation
• any new merged undocumented PR for new feature should be done with creating a new issue on godot-docs as well, to keep track of any additional incoming missing documentation.
  At least to have some insight in case of where eventually to focus documentation effort.
• create new issue on godot-docs or any call for (third-party ?) contributions to update a PR before merging it

I know that can slow things, but all decisions regarding this are just a matter of balancing between of what you think is acceptable documentation debt and having quickly new features merged.

Don't let documentation debt explode!

• Documentation debt will be paid (or not...) by time spent on it instead of even more features.
• Documentation debt cost will be time spent by end users (game dev) for trying to figure out what a specific thing does.
• Documentation debt cost will be time spent by users and current engine contributors offering support to other devs.
• Documentation debt cost is bad reputation and user base. (and less new patreons, etc.)

Technical debt
From Wikipedia, the free encyclopedia

Technical debt (also known as design debt[1] or code debt) is a concept in software development that reflects the implied cost of additional rework caused by choosing an easy solution now instead of using a better approach that would take longer.[2]

Technical debt can be compared to monetary debt.[3] If technical debt is not repaid, it can accumulate 'interest', making it harder to implement changes later on. Unaddressed technical debt increases software entropy. Technical debt is not necessarily a bad thing, and sometimes (e.g., as a proof-of-concept) technical debt is required to move projects forward. On the other hand, some experts claim that the "technical debt" metaphor tends to minimize the impact, which results in insufficient prioritization of the necessary work to correct it.[4][5]

As a change is started on a codebase, there is often the need to make other coordinated changes at the same time in other parts of the codebase or documentation. Required changes that are not completed are considered debt that must be paid at some point in the future. Just like financial debt, these uncompleted changes incur interest on top of interest, making it cumbersome to build a project. Although the term is used in software development primarily, it can also be applied to other professions.

[eon-s]

Creating a list of undocumented features for contributors may be better than forcing developers to clearly document in English the additions (language that many may not handle very well in this global ecosystem).

The utility of a list can be, apart from making easier to track undocumented features, for being able to contact the developers and ask about a particular feature they have added (some examples can be autotile and custom visual script nodes).

[groud]

This is probably not going to happen, we already have a lot of work to do on the engine. As all unfixed documentation issues suggest, listing what's undocumented does not make the documenting the engine faster. So automatically creating issues in another repository is a no-go for me, we already have the possibility to know what's not filled in the reference, I think this is enough.

We can try to encourage people to document their work, but generally programmers don't like to do so, we can't force them, and we're not going to refuse a contribution because it's not documented. So there's not a lot of solutions.

The only thing that has been really efficient in improving the documentation was to organize doc sprints as GDquest and KidsCanCode organized. We may make those more often.

[eon-s]

Well, now that I think it a bit better, there already is a "new features" list https://github.com/godotengine/godot/pulls?q=is%3Apr+is%3Aclosed+label%3A%22feature+proposal%22

It will need a better way to track documentation but that may be a docs repo issue.

[groud]

Well we have the "documentation" label too.

[vnen]

We can at least ask people that are adding features or binding new API functions to document them too. I believe most of the people is willing to that if asked. We already ask for code changes, we can ask for documentation too.

[groud]

Well I guess so, but on the other hand most features are not perfectly done when the PR is merged. So between releases the documentation might have to be re-written several time, which is not really efficient.

[raymoo]

@groud You only need to document the parts that change, though. If something is complex enough to require several rewrites then the documentation is probably not a big share of the required effort.

[Zylann]

Note you could write doc for something not implemented yet. In a sense, the doc explains what is intended, expected behaviors and functionalities. If not written, that info will only be in the PR author's head, though we tend to write this down in the issues themselves.

[neikeq]

IMO, we should have documentation in the C++ code. This way it's easier to maintain for other contributors, and the documentation team can have a look at the C++ documentation when writing the scripting class reference documentation.

This also prevents contributors with bad (english) writing abilities to affect the documentation quality. The description comments in C++ need not be written with that much care into details, while the class reference does.

[eon-s]

Description can be in the PR too, some contributors are already doing a great job in details on the PRs and may be easy to track by the documentation writers.

Also there can be changes on some features and the contributor forget to edit the previous code comment making things more confusing.

[Calinou]

The class reference completion status can now be viewed here. It's much better than it was in early 2018 :slightly_smiling_face:

As of recently, we've been pushing PR authors to document newly exposed properties/methods whenever possible. We may write it in CONTRIBUTING.md to make it a strict requirement in the future.

[Calinou]

Closing in favor of https://github.com/godotengine/godot-docs/issues/3390, as it includes this particular question (among many others). The main Godot repository is now intended to be used for bug reports only.