Skip to content

Conversation

@AThousandShips
Copy link
Member

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

@AThousandShips AThousandShips requested a review from a team October 22, 2025 11:08
@AThousandShips AThousandShips added the enhancement New feature or request label Oct 22, 2025
Copy link
Member

@Ivorforce Ivorforce left a 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.

@AThousandShips
Copy link
Member Author

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

Comment on lines +62 to +70
Finally it's also important to know what *not* to document; there are a some cases
where things should be left out of the documentation to avoid causing problems.
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; so 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.
Copy link
Member

@Calinou Calinou Oct 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use shorter sentences (especially since the paragraph is long):

Suggested change
Finally it's also important to know what *not* to document; there are a some cases
where things should be left out of the documentation to avoid causing problems.
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; so 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.
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.
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.

Comment on lines +72 to +74
Anything that is documented is also generally considered part of the official API,
meaning that changing it could be considered breaking compatibility, this risks
limiting what changes can be done even when necessary.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Anything that is documented is also generally considered part of the official API,
meaning that changing it could be considered breaking compatibility, this risks
limiting what changes can be done even when necessary.
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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants