-
-
Notifications
You must be signed in to change notification settings - Fork 11
[Documentation] Add information on what not to document #17
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
base: main
Are you sure you want to change the base?
[Documentation] Add information on what not to document #17
Conversation
Ivorforce
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This could use a comment about what to do in this situation.
I'm thinking about something like this:
- User experiments finds some strange behavior
- User tries to document it
- Area maintainer is notified, regards the behavior as bug
- Maintainer fixes the bug
- Documentation PR is changed to document the new, intended behavior.
|
Realized I forgot a note that I was going to add, something like "If you are uncertain, please ask the relevant team" Note that this is more for things like "after creating a node X is in Y state" or "drawing two things in a row has X effect", as opposed to not documenting bugs, though that is important too |
6d07299 to
8752241
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the new section is great, but it's a little too long for my taste.
I tried to juggle the information around a bit, and I think i've arrived at something that brings the same message across, but uses less words.
Ultimately it's a matter of taste though, so feel free to adapt my suggestions in a way that feels right to you!
| Finally, it's also important to know what *not* to document. There are some cases | ||
| where things should be left out of the documentation to avoid causing problems. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would be good to get the actionable stuff out of the way first. Explanations can follow later, for those interested.
| Finally, it's also important to know what *not* to document. There are some cases | |
| where things should be left out of the documentation to avoid causing problems. | |
| Finally, it's also important to know what *not* to document. There are some cases | |
| where things should be left out of the documentation to avoid causing problems. | |
| In short, do not document something in the following cases: | |
| - The behaviour is a bug. In that case, please [report the bug](https://github.com/godotengine/godot/issues) instead. | |
| - The behaviour is not intended (also called an "implementation detail"). |
| Some behaviors or details of how some part of the engine works might be unintentional, | ||
| unknown to the maintainers, or be an implementation detail rather than part of the | ||
| real goal of that feature. This means that these details might change when bugs are | ||
| fixed or new features are added, as they are not part of the intended behavior or | ||
| goal of the feature. Documenting them would risk making people rely on things | ||
| that might change in the future if maintainers are not aware that this has been | ||
| documented. | ||
|
|
||
| Anything that is documented is also generally considered part of the official API. | ||
| This means that changing it could be considered breaking compatibility. This risks | ||
| limiting what changes can be done even when necessary. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Given the above, I think this could be shortened:
| Some behaviors or details of how some part of the engine works might be unintentional, | |
| unknown to the maintainers, or be an implementation detail rather than part of the | |
| real goal of that feature. This means that these details might change when bugs are | |
| fixed or new features are added, as they are not part of the intended behavior or | |
| goal of the feature. Documenting them would risk making people rely on things | |
| that might change in the future if maintainers are not aware that this has been | |
| documented. | |
| Anything that is documented is also generally considered part of the official API. | |
| This means that changing it could be considered breaking compatibility. This risks | |
| limiting what changes can be done even when necessary. | |
| To understand why we don't want to document unintended behavior, please consider that anything that is documented could be considered part of the official API. | |
| This means that documenting unintended behavior could risk making people rely on things | |
| that need to be changed in the future, limiting what we can change without breaking compatibility. |
| This means that the documentation team should make sure that area maintainers review | ||
| documentation PRs that add previously undocumented behavior, and that area maintainers | ||
| should review the documentation of PRs adding new features, to make sure that internal | ||
| details are not documented. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| This means that the documentation team should make sure that area maintainers review | |
| documentation PRs that add previously undocumented behavior, and that area maintainers | |
| should review the documentation of PRs adding new features, to make sure that internal | |
| details are not documented. | |
| To avoid accidentally documenting unintended behavior, :ref:`area maintainers <doc_areas>` should always review changes to their respective area's documentation. Facilitating this is the responsibility of the documentation team. |
Still a bit rough and looking for some feedback, but something I thought important to document
Could be its own entire page as well if we want to expand a bit further even, the paragraphs are a bit lengthy so might be best, and it might not be in the right place I'm not entirely sure where it would be best placed