Skip to content

[WIP][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.

Sign up for GitHub

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[WIP][Documentation] Add information on what not to document #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions documentation/guidelines/content_guidelines.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,20 @@ documentation's scope. For example, you could link to an introduction to
programming in the getting started guide, or a website that teaches math theory
in the math section.

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.
Comment on lines +62 to +70
Copy link
Member

@Calinou Calinou Oct 22, 2025 •
edited
Loading

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.


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.
Comment on lines +72 to +74
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.

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.


Limiting cognitive load
~~~~~~~~~~~~~~~~~~~~~~~

Expand Down