Skip to content
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

Move most of Scripting/Core Features section to new Core Features section #10384

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

tetrapod00
Copy link
Contributor

@tetrapod00 tetrapod00 commented Dec 7, 2024

Extracts most tutorials from the Manual/Scripting/Core Features section to a new Manual/Core Features section, with subsections for Nodes, Scenes, Signals. I didn't make a subsection for Resources since there is only a single page.

Why:

  • None of these tutorials are really about scripting per se.
  • These are very core features of Godot, and as such should have a more prominent place in the sidebar.
  • Currently these tutorials are somewhat jumbled. Tutorials about a single topic, like scenes, are seemingly out of order, interspersed with tutorials about other topics. Tutorials seem to assume a reading order which no longer exists.
  • Adding new information about any of these topics is currently messy. If you want to add a new page, it goes in the unsorted selection of tutorials in the Manual/Scripting/Core Features section. The new structure will provide a much more natural place to put any new tutorials.

Known side effects:

  • A few links to these tutorials from the class reference will break. The CI is currently failing for this reason. Draft PR to fix this is ready: Fix tutorial links after documentation reorganization godot#100158.
  • External links to these pages will break. Since we are already above the limit for redirects (IIRC), I didn't add any redirects yet, but I can.
  • I think the current Giscus comments on these pages will break. I'm not sure how to mitigate that.
  • Probably some existing PRs will break and need rebasing. I haven't checked closely, but I can't specifically recall any that PRs that are near merging that will break.

Future plans:

  • Go through each of these pages and clean them up so they make sense in the new reading order. There are explicit references to "what we have covered so far" and similar which no longer make sense. I left that out of this PR to minimize noise.
  • IMO, and this is subjective, core features like signals, nodes, and scenes should be documented in the Manual at least briefly in a dedicated way, rather than relying on the Getting Started section. So in the future I'd like to add a dedicated introduction page to each of the subsections here. One problem with relying on the Getting Started section on Signals is that since the Getting Started page exists as part of the introductory sequence, there is a limit to how much information can be packed into it, and a limit to how detailed and technical it can be. In the Giscus comments on that page, there are already requests for additional information that IMO really can't fit in an introduction to signals in the Getting Started section. Adding a dedicated page for signals in the manual can fix that.

Sidebar comparison:

Scripting/Core Features section:

Before After
firefox_UyAau4jc1N msedge_V8e18QkoU1

Core Features section after:
msedge_fQ4DoGx4I1

msedge_8T29y4qo2c

msedge_bFS6TMF1Ie

msedge_kInGxlEjrw

…ategory

Extract most tutorials from the Manual/Scripting/Core Features
section to a new Manual/Core Features section, with subsections.
@tetrapod00 tetrapod00 added content:organization Issues and PRs related to reorganizing the content area:manual Issues and PRs related to the Manual/Tutorials section of the documentation labels Dec 7, 2024
@mhilbrunner
Copy link
Member

I agree with this change, however I'd like to wait until we implement a fix for the redirect issues until we move pages around. Should hopefully find some time to look into that soon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:manual Issues and PRs related to the Manual/Tutorials section of the documentation content:organization Issues and PRs related to reorganizing the content
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants