-
-
Notifications
You must be signed in to change notification settings - Fork 2.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[META] Require companion ReadTheDocs PR for all new feature PR's #4800
Comments
I definitely agree with this issue in general and don't think it needs any further discussion, especially if this policy goes along with things like #4706. However, I'd like to also have some standards and stricter guidelines established for the documentation before even considering to enforce this. The main concern for me here is how the documentation for these features (especially events and hooks) should be structured and what extent it should take. First of all, it's clear that entire subsystems should at least get their own article. If they are very large and complex in scope, a new section probably is appropriate as well. Events, on the other hand, generally don't warrant an entire article of their own. Instead, I propose that they be subsections in generic event category articles or those for the affected subsystem. The categorization could take some inspiration from my test mod proposal. Considering I'm more or less in charge of Forge's web design, including the docs, I'd look into allowing deeper hierarchies. Currently, they are limited to sections and articles, but more complicated structures might be required. Finally, it's worth discussing how much information event documentation should contain. For most events, detailed JavaDocs already suffice now, so the documentation section in my opinion must at least contain that in addition to a simple example if the usage isn't completely trivial. I think the main purpose of extensive documentation in a central place is discoverability of features. Rookie modders and even veterans sometimes are oblivious to the tools available to them or don't know what feature exactly to look for. One point I'd also like to stress is that documentation should not serve as a tutorial with step by step guides on how to do a very specific thing. Instead, we should strive for generic descriptions of features and how to use them including simple examples that are easily extrapolated. This is especially important for large subsystems, as drifting into a tutorial-esque style is easier there. |
Ya, this is never going to happen. We already get a backlash for asking people to follow the few rules we have for PRs. We're not gunna punnish the good developers we do get because they don't want to write documentation. I usually let the docs repo do its own things, in the understanding that it doesn't interfere with the rest of the project. So you're stepping outside of your bounds with this. |
I agree that requiring documentation would definitely be excessive, but I believe at least a small suggestion towards documenting features wouldn't hurt to include in the guidelines. I'm sure it is something that is often overlooked, even by those who enjoy explaining their changes. Something along the lines of "Regarding new features, contributions to Forge's documentation explaining its functionality and use cases would be appreciated if you feel inclined to do so" could work, possibly. |
I think we can all agree the state of documentation is pretty bad, and gets worse as new features are pulled.
So I'd like to propose that from now on we require all new feature PR's to come with a companion PR to MinecraftForge/Documentation, which will be merged upon merge of the main PR (or closed if the main PR is closed).
What qualifies as a feature PR?
What should the documentation pull contain, at minimum?
The text was updated successfully, but these errors were encountered: