Audit of the Godot user manual

[NathanLovato]

About this review of the user manual

My current mission is to find the pages and changes that can bring the most significant improvements regarding the user manual. The goal is to open individual tasks for each missing page or page that needs changes. This audit is meant to help contributors work towards a solid reference manual and a better companion to the class reference than it currently is.

The focus is solely on the user manual here, that is, pages that are not part of the class reference. To report incomplete, unclear, or missing docstrings in the API reference, please open an issue in the [Godot engine repository](https://github.com/godotengine/godot/issues).

Any point below ending with a "?" is something I'm still unsure of.

How you can help

Below, you will find a review of the Getting Started and Tutorials sections of the docs. I read all pages one-by-one and took note of the ones that should be rewritten or improved in priority. I also listed features that are completely undocumented and we should cover in the manual.

After reading the review notes below, let me know if:

• You have any feedback or critiques.
• There are other missing features you'd like to see covered.

Note that we will remove outdated step-by-step tutorials from the documentation.

Also, we will not include more step-by-step tutorials about creating specific types of games from scratch. Instead, we want the manual to cover Godot's features in general.

For example, we won't cover topics such as "Creating a 3D platformer from zero" or "Creating an MMORPG in Godot." Two exceptions will be Chris's introductory tutorial "Your first game" for 2D, and a future 3D counterpart.

Note: all changes only affect the latest version of the documentation. Content removed in the Godot 4 documentation will still be available in Godot 3.2 and prior versions.

Getting started section

Reviewing existing content

The section contains content that goes deeper than what you need to get started, with Scripting and Project workflow being comprehensive references.

1. Step by Step is going to get a rewrite. I'll cover the plan in detail in a separate issue.
2. Editor manual is a small section that doesn't really cover the Godot editor: Command line tutorial and Using an external text editor don't fit, which leaves it with only one article about shortcuts. I'd remove the section altogether, move its content to other relevant categories, and have docks covered in the most appropriate section, as some are already.
3. Scripting: move to Manual. If possible, I'd add a paragraph or two to the section page to introduce the available languages. In general, I'd add a bit of text and images to section pages to let the user know what they're supposed to find in each.
4. Project workflow: move to Manual. I'm not sure about this section. I'd move its subsections up, e.g., there's quite a bit in Export (building the game for various platforms) and Best practices. And they're not exactly workflow to me.
   1. Assets workflow: rename to Asset pipeline. I'd move this out of project workflow
      1. Lacking an overview of supported assets and formats.
   2. Project Setup: Move content out and remove the section
      1. Project organization describes best practices to organize your project's files -> move to Best practices.
   3. Best practices: good content, needs edits to improve clarity and organization in individual pages.

Suggested reorganization and structure

Intention: give users all the information they need to get up to speed with the engine in a short amount of time. The content should frequently link to other pages in the user manual for more information.

The content should be split into two series adapted respectively to beginners and experienced developers.

I will detail the plan for these in a separate issue.

Getting Started

• Introduction: content that any user should read first, and that's shared between the getting started series. Brief overview of Godot and what it can do for you. Brief look at the editor. See #1880
• I'm a beginner
• I'm a developer

Tutorials section

Intention and goals:

1. Make the section shorter and easier to navigate.
2. Make it easier to put content in the right section. Some content is out of place at the moment.
3. Track down every undocumented feature to work towards a reference manual covering every main core feature.

General notes:

• Rename to Manual (other options: Learn, Features). The name should clarify that this is intended as a reference manual and not a library of step-by-step tutorials.
• Each sub-section should have one or two introductory paragraphs to let the user know what they can find there. Currently, it's only a list of links. Some short description would help set the reader's expectations but also link to related pages.
• It might be useful to summarize pages at the top, explaining what problems the page addresses or what techniques it teaches in a short sentence. Often, the title is not enough. Doing so would allow the reader to quickly move to another page if it's not the information they're looking for.
• Replace acronyms
  • I/O: Rename to something clearer. "File I/O" or "File Input/Output"
  • GUI: Rename to "User Interfaces (UI)".
• There are too many sub-sections, some almost empty, some not meaningful.
  • Asset Library: move to Community.
  • "Creating content" contains two tutorials about procedural 3D geometry. I'd merge it into 3D.
  • Miscellaneous has content that should be in other sections and doesn't help users find information, so I'd remove it. Topics like pausing the game and signals could move to Scripting, for instance. Binary serialization is definitely "File I/O".
  • Debug: merge into Scripting.
  • Legal: move into About -> Licenses. We can link to it from the introduction and other places that refer to legal or licensing issues.
  • Multi-threading and Optimization: merge into a section about performance?

There are more sub-sections I'd like to remove by moving their content, like "Viewports", whose name may not be meaningful to some readers. For instance, we could have a section dedicated to rendering instead. That section could cover canvas layers, drawing, viewports, and more.

Sub-sections

Scripting

To move from Getting Started to a new Scripting sub-section. Vnen suggested moving GDNative to Scripting: #1880

2D

• Split Using Tilemaps into Creating tilesets and drawing maps with tilemaps
  • Because there is a lot more to say about each, we're missing a comprehensive guide for either.
• Viewport and canvas transforms is a brief article about some low-level inner workings of the engine. It doesn't directly expose or solve a problem for the user. There's only one problem and solution exposed at the bottom of the page.
• Custom drawing in 2D: needs some stylistic changes (titles feel informal: "Why?", "But…", "OK, How?").

Missing:

• YSort and Z sorting in general
• Parallax backgrounds
• Working with cameras in 2D
• Remote transforms?
• Some suggested tools and workflow to design 2D levels?

3D

The content in the section needs a reorder. E.g. Optimizing 3D Performance is in 3rd position in the TOC, before articles like the overview of the Spatial material.

Also, many articles in this section will likely need changes with the new rendering engine.

• Introduction to 3D: Could be part of the Getting Started guide. The article as it stands may need to be broken down and extended. It describes a variety of 3D-related features, navigation, views, environments, without detailing any too much. I'd split them into different pages to flesh out each concept and link from the introduction.
• Using 3D transforms: I'd reorganize it. There's quite a bit of info about euler angles to explain why they aren't great. I'd shorten that, then focus on the examples of the vector code for movement.
• 3D lights and shadows: I'd focus on lighting first, then adding shadows, then troubleshooting common issues with lights and shadows (bias, etc.).
• Using MultiMeshInstance: rename into something more descriptive of the problem it solves, like "Drawing many copies of a 3D object". Maybe list the pros and cons at the top. It's useful and intended to draw thousands of mesh instances in one batch, and each can have unique transforms. I felt the introduction could be clearer.
• Optimizing 3D Performance and Animating thousands of fish: I'd move it to a section dedicated to performance optimization and link to it from the 3D section.
• FPS tutorial: remove. It's outdated and doesn't follow the GDScript style guide. Also, it's GDScript-only. We should try to have at least all code blocks offer GDScript and C# alternatives throughout the docs.

Missing:

• Movement in 3D, the counterpart to the 2D article. Giving some good code examples for simple 3D movement, linking to Physics for more information.
• We lack resources dedicated to level design. Not just mentioning the Gridmap, but also how you may design a level in Blender, or in Godot. An overview of the tools at your disposal and some suggested workflow(s).
• Some overview of tools and workflows for level design in 3D. I think it could complement the overviews of the GridMap and CSG well.
• Cameras: clipped, interpolated cameras, spring arm.

Audio

• Split audio effects to a dedicated page.

Missing:

• Maybe using AudioStreamPlayer2D, 3D, and Listener nodes in conjunction with areas for positional audio. In particular, we're missing concrete use case examples.

Physics

Make sure that there's clear documentation on all types of PhysicsBodies and how to use them. Have a dedicated page for each body or are class and a general introduction page that puts them all in the big picture and includes the relevant links.

• RigidBody: phrasing can be simplified. Lacking examples compared to the KinematicBody2D page.
• Kinematic character (2D): the writing style feels informal, and the article could be more straightforward.

Missing:

• Physics joints (2D)
• Physics joints (3D)
• Vehicle physics, because there's the built-in VehicleWheel node.
• ProximityGroup. It could also be in Performance optimization

Missing: Navigation

In particular, this section would cover 2D and 3D navigation and pathfinding. I would also include an article giving an overview of tools at your disposal to implement AI. For example, the VisibilityEnabler and Notifier nodes or creating a line of sight with RayCast and detecting other agents with Area nodes.

Guides could include:

• Real-time navigation (3D)
• Real-time navigation (2D)
• Navigation on a TileMap?
• Path and PathFollow
• Astar and Astar2D

Animation

• Introduction to 2D animation features: Remove "2D" from the name.

Missing:

• Information about animation options in 3D. I would cover the 3D IK and upcoming FABRIK in this section.
• We should probably link to importing animated characters from Blender, and maybe cover attaching objects such as weapons via the BoneAttachment node.

Inputs

• Rename InputEvent. It's more of an introduction to input in Godot. The article could use some edits to focus on giving an introduction and overview of input management in the engine and editor.
• I'd split the input map to a dedicated article and cross-link to it. There's quite a bit to cover regarding this editor alone.
• Mouse and Input coordinates: Rename to Mouse [and touch] input and add more detail.
  • How to get input when clicking on objects in the world.
  • How to keep track of the mouse's motion in 2D and 3D.
  • Link to UI input article for UI-related input
• Input examples: covers some essential techniques and topics not covered elsewhere. I'd split it into relevant pages. Examples should be part of corresponding guides, like mouse-related examples in "Mouse input" or joystick examples in "Gamepad input".

Missing:

• Specifics of UI input. Capturing or passing mouse input, dedicated input callback function, focus, focus neighbors, keyboard shortcuts, and others.
• Creating custom types of input events. For instance, a class that generates finger swipe events.

I/O

• Data paths: the name could be clearer. It's about writing paths to access files within Godot projects and where the user or cache data is saved. I'd suggest "File paths in Godot".

Missing:

• Options to serialize and load data: overview of the available tools and formats. You can use JSON, CSV, text, but also Resources and special resource types like PackedScene.
• Resources may have a place in this section or Scripting, and linked to throughout the docs.
• Creating and loading custom resources?

Internationalization

Wait for GSoC work from @SkyLucilfer.

• Internationalizing games isn't straightforward for users. I'd give the user an example of writing and importing a CSV file on top of the following operations.

GUI

• Link to the (currently missing) UI input guide in the Inputs section.

Missing:

• Overview of Godot's UI system and framework.
• Workflows to design user interfaces in the editor. You can often choose to work either with containers or the Layout menu options. For instance, there are many cases where a CenterContainer and Layout -> Center produce the same result. Often, you need a combination of containers and layout options.
• Best practices to design user interfaces in Godot: creating small, reusable components and using aggregation.
• Many theme capabilities and recommendations to use overrides.
• Working with text and fonts.
• Working with focus neighbors
• Concrete example of a custom container? This should be in its own article.
• Look at all types of Control nodes, their purpose, and usage in the editor.
• Creating UI that adapts to different resolutions and screen sizes.

Viewports

I'd like to move the content in this section to other places:

• Multiple Resolutions is a general topic that about every user will want to read. It's not directly related to the viewport node; instead, it's mostly about the window project settings. To me, this is related to "setting up your Godot project."
• Two of the four articles are about shaders.
• The remaining article is the only one that's dedicated to the Viewport node and class, and it focuses on 3D.
  • The 2D section has a tutorial about viewports in the context of 2D, so we could move the 3D viewport tutorial into 3D.

Shading

Rename the section to Shaders, as it's all about shaders and not shading in general (using materials, lighting, etc.).

• Shading reference: rename to "Shader reference"
• Shading reference / Shaders and Your First Shader / What are Shaders? are both intros to shaders. They could use a merge.
• I'd rename the titles Your first CanvasItem and Your First Spatial shaders to respectively 2D and 3D shaders. The keywords can be inside the article but if I were new to Godot, I'd search for 2D and 3D.
  • Also, I'd avoid having articles named "part 1" and "part 2" or (continued), and instead favor titles that describe the content as closely as possible.
• Your First Shader / What are Shaders?: I'd move this article up a level, and name it something like "Introduction to shaders"
• Remove Intro to shaders: 2D and 3D water. I put our collab video series with Bastiaan Olij a long time ago due to the docs' lack of content, but it's now unnecessary.
• Migrating to Godot's shading language: rename to "Converting GLSL to Godot shaders"
• Godot shader language style guide: rename to Shaders style guide

Networking

Feedback from @menip: had a bad experience getting started with networking in Godot, following the docs. This needs investigation. He wrote MIT-licensed tutorials and a general overview here: https://gitlab.com/menip/godot-multiplayer-tutorials/-/blob/master/NetworkingBasics.md

Asset Library

• Using the AssetLib: rename into Using the Asset Library

VR

I need feedback from people who develop VR and AR games.

Plugins

Looking good to me overall. It covers the basics. For mobile platforms, only Android plugins are covered. Is there no similar feature for iOS?

• Move Android plugins documentation to Platform-Specific.

Platform-Specific

Again, without experience releasing games on mobile and consoles with Godot, I lack the experience and knowledge to know if the content is complete.

Missing:

• iOS counterpart to Android documentation.

Debug

Missing:

• Some comprehensive guide about using the profiler and Monitors. We wrote some recently for that. We'll gladly contribute the pages to the docs.

Miscellaneous

Remove the section, properly categorize each article.

• Fixing jitter and stutter: move to Rendering or 2D
• Handling quit requests: move to Inputs?
• Pausing games: move to Inputs or Scripting?
• Binary serialization API: move to Input and Output (I/O)
• Running code in the editor: move to Plugins
• Change scenes manually: move to Scripting?
• Differences between GLES2 and GLES3: move to a new Rendering section?
• Instancing with signals: move to Scripting
• State design pattern: move to Scripting or remove?

Development and Community

I'm not in a good position to judge the engine development documentation at the moment. I would need to work with core contributors there. As with every other section, if possible, the main sub-section should have a paragraph describing the content and linking to other relevant or complementary sections, if applicable.

I'll work on Community -> Contributing a bit for the content guidelines and propose and implement changes in separate issues.

User requests

• Documenting the engine's core and inner-workings. In particular, a user wanted to rewrite the core loop.

[clayjohn]

This is a great start! It shows how quickly decentralized efforts make things messy. We definitely need a clear vision for how to organize the sections going forward so that maintainers can ensure that pages find their proper place.

One thing to add to your consideration is the massive overhaul @lawnjelly and I just worked on for the 3.2 optimization tutorials. Much of the content is general in nature and will apply to 4.0, but we are waiting for rendering and GDScript to get further along before porting the section to 4.0. but if you look at the 3.2 docs you'll see how large the section has become. Notably, the 3D optimizations content was moved from "3D" to "optimizations".

[KoBeWi]

Soo I have a list of random features that are hidden in the editor and not indicated anywhere, like "you can drag and drop a file to Script Editor to insert its path" or "if you move a node in the scene tree while holding Shift, it will keep local transform". My initial idea was to put these into "tip of the day" window, but the proposal was rejected. So I thought it would fit into some "101 useful Godot tricks" page or something. What do you think?

[Calinou]

interpolated cameras

InterpolatedCamera has been removed in the master branch. It can be replaced by a Camera3D with some custom code for lerping.

Platform-Specific

Again, without experience releasing games on mobile and consoles with Godot, I lack the experience and knowledge to know if the content is complete.

There are some more console-specific things we could list there. Nothing below is Godot-specific, but it probably doesn't hurt to document it anyway. Most console OEMs impose certain requirements on games released on their console:

• The game must have a title screen where you press Start to enter the main menu.
• 2D elements such as menus and the HUD should leave some margin with the screen's edges to avoid issues with TV underscan. (For an example of this, compare the HUD of Minecraft's console editions with the Java Edition.)
• No graphics settings should be exposed to the user in menus. (That said, nothing prevents you from adding cheat codes to change graphics settings or unlock the framerate.)

That said, there are probably public documents out there listing stuff like this with much more detail – we might want to link to those directly instead.

[adimasduvitra]

So far so good!

Differences between GLES2 and GLES3: move to a new Rendering section?

Yes please, rendering needs its own section.

[geekrelief]

This might be outside of the scope of what you're working on, but since the docs are be revamped I wanted to throw this out there.

I was toying with tagging the API in order to create a category page to improve searchability and discoverability of the API. The engine source is organized into various sections like core, editor, scene, audio, gui, etc. Organizing by category helps with discoverability via browsing. It's one reason why I sometimes resort to browsing the source since some class pages are empty e.g. VisualShaderNodeVec3Uniform.

If everything was tagged it could be included into the meta description tag of each page. Example categories: data, scripting, rendering, audio, physics, geometry, collision, input, engine, gui or ui, animation, math, networking, arvr or xr, logic, 2D, 3D, etc. This would help with search engine searchability.

Some examples: AABB: math, geometry, physics, collision Area2D: geometry, physics InputEventMIDI: input, audio MainLoop: engine FuncRef: scripting FileDialog: gui, ui, io EditorFileDialog: editor, gui, ui, io X509Certificate: networking, crypto

One thing I ran into with this idea was that the navbar created by sphinx expects each page to only have one entry. So if for example AABB is open but was navigated to via the "geometry" category the navbar will show AABB open under the Class Reference section. I'm not sure how to get around this unless we avoid repeating the classes in the navbar.

Another issue might be that it would be confusing for users to see a class in multiple categories. While it makes sense to see InputEventMIDI in input and audio, in a bookstore it would be filed under only one category.

If we want to get fancy, the category page could have checkboxes for selecting filters by tag like on steam where you can search for games by category like "indie" and "action". The category page or search navbar could have filters by tag.

[MarcusElg]

2D tilemaps are soon gonna be totally redone and will probably be part of 4.0 so isn't it a bit unnecessary to do a new tilemap tutorial right before the huge upcoming changes?

[Myran]

A GDScript one page cheat sheet with common syntax, logic and expressions would be very useful.

GDScripts is probably not the only programming languages for most users and the specific syntax can be hard to remember when context switching. I have to look up that switch is called match every time :)

Currently I have a tab with https://docs.godotengine.org/en/stable/getting_started/scripting/gdscript/gdscript_basics.html however a one page summary easily reached from the main doc page could be greatly benificial both for beginners and advanced users.

[Calinou]

@Myran This could be better addressed by contributing a GDScript page to learnxinyminutes.com (which I'm working on right now).

[NathanLovato]

One thing to add to your consideration is the massive overhaul @lawnjelly and I just worked on for the 3.2 optimization tutorials.

@clayjohn Where can I find these? I'm working from a locally built master branch, but the optimization section was as described above.

Soo I have a list of random features that are hidden in the editor and not indicated anywhere,

@KoBeWi they're not so random, they're each related to a specific docker or interface. So it sounds like we should probably have an Editor section that covers each part of the editor's interface. The related features should be grouped there.

With a reference manual, consistency is important. We don't want to bundle unrelated features and tips in some pages because they become harder to find and different from the rest of the content.

@Calinou Thanks for your notes and PRs. Note that when a change doesn't need review, you can commit directly without opening a PR. E.g. for the CSG page title. Although we should probably open issues first so these changes can be tracked.

Regarding consoles, each manufacturer sends precise guidelines for developers to pass their QA so I wouldn't bother putting it in the docs. The only thing I saw that I'd change is the porting to consoles can cost upwards of 1000$, which is lacking a 0. The figure doesn't seem to take into account the months of full-time development work it can take to port a game to console(s).

Also, note I've chosen not to make any changes directly on purpose: to get review and feedback, plus a green light before moving forward. I'll open tickets for each task once they've been greenlit.

@geekrelief Yes, your request is beyond the scope of this job. As mentioned in the first issue, I'm only working on the reference manual. And on content in particular. You could open a proposal for your idea.

isn't it a bit unnecessary to do a new tilemap tutorial right before the huge upcoming changes?

@MCrafterzz this audit is a first step to plan improvements for Godot 4.0. Rest assured we'll rewrite the pages after the editor's redesign if it's coming for Godot 4.0; not before. I think it's not guaranteed it'll make it in 4.0, as Gilles should start working in November, if I'm not mistaken.

[Calinou]

@NathanLovato The optimization tutorials are here: https://docs.godotengine.org/en/3.2/tutorials/optimization/index.html

They're not in the master branch yet.

The only thing I saw that I'd change is the porting to consoles can cost upwards of 1000$, which is lacking a 0. The figure doesn't seem to take into account the months of full-time development work it can take to port a game to console(s).

I only took into account the licensing costs, not the development costs themselves. Otherwise, I expect the console porting process to cost much more.

[NathanLovato]

Ah! Thanks. @clayjohn shouldn't we have them in master? Even if they're going to change later or even soon, master should be the work-in-progress branch for the docs.

@Calinou Thanks and gotcha. Regarding consoles dev, I'd try to make it clear that it's costly and difficult regardless of the engine, mainly because there's a lot of misunderstanding regarding what's involved in porting a game to consoles. And that even people who dev. e.g. with Unity still work with publishers for console ports for that reason.

[NathanLovato]

I removed the two addressed issues from the audit. Please don't create individual PRs for tiny changes, as that's making it more work than it needs to be. If you'd like to tackle small tweaks like renaming a page, please bundle them together. Even if you make multiple commits as part of one PR.

[skyace65]

I looked over the import pages to check if any of them were missing a supported format list. As far as I can tell they all show what formats they support, unless Godot supports more audio formats than WAV and OGG. Though the 3D page could be more specific on what gets imported in a scene in each format.

However, it turns out the docs are lacking any information on how to import images as anything other than a texture. And there's enough settings with those other options that it might be worth making a part 2 page.

[skyace65]

I'm not sure if moving debugging to scripting is a good idea. It has scripting tools, but there's other non scripting stuff in there such as the Visual Profiler, Monitors, Video RAM, and Misc (UI stuff) tools. However I do agree with combining the other sections.

[NathanLovato]

However, it turns out the docs are lacking any information on how to import images as anything other than a texture. And there's enough settings with those other options that it might be worth making a part 2 page.

Should we add one or more missing pages about "Missing Import settings"?

I'm not sure if moving debugging to scripting is a good idea. It has scripting tools, but there's other non scripting stuff in there such as the Visual Profiler, Monitors, Video RAM, and Misc (UI stuff) tools.

To me, the profiler, monitors, and ram would go to performance optimization as they're tools to monitor the execution speed of your game. You'll find them in the many pages @clayjohn and @lawnjelly wrote about performance in the 3.2 branch.

This leaves us with a short debugging section that would only contain the debugger, breakpoints, remote scene tree, and I guess the Misc section. That's a bit lean, which is why I wouldn't dedicate a section for them. I would put it closest to the most related content, which is scripting, as you use the debugger in conjunction with the script editor.

If Misc is only UI, i'd put it in the user interface section.

What do you think?

[skyace65]

That sounds good to me.

[menip]

Re: Networking section

When I was learning about networking sometime last year, I did not have such a good time. I ended up writing a set of tutorials about it: https://gitlab.com/menip/godot-multiplayer-tutorials

In particular, the basics page may be useful as a reference: https://gitlab.com/menip/godot-multiplayer-tutorials/-/blob/master/NetworkingBasics.md

[clayjohn]

@NathanLovato you can find a deeper discussion in the PR adding the optimization tutorials. But we ended up deciding not to merge them into master yet because of the significant differences between 3.2 and master. Another PR is needed to port the relevant chunks to 4.0. Given how much work that will be, and given that we don't know exactly what 4.0 will look like, we decided to wait.

If it helps you, I can put together a PR that cherrypicks the majority of the optimization tutorials so you have a shell to work with in your major reorganization. We would just have to have the understanding that much of the content is subject to change because 4.0 is still in rapid development.

[NathanLovato]

@menip thanks much for the feedback. I'm adding this to the first issue. Would you be ok if we copied some content from your documents? I see they're MIT-licensed. We'd mark you as the commit author or co-author, of course.

I can put together a PR that cherrypicks the majority of the optimization tutorials

@clayjohn definitely! It's okay that a lot is subject to change. The idea of the master branch is it's a work-in-progress version of the docs, and a preview of what everyone is working on by the next major release. There's a lot that's going to change on many fronts.

[skyace65]

I was going through the doc issues and found two that seem relevant to this since they're about moving doc pages, #1880 and #1169. Are these things we want to change or not? And if not we should close the issues.

[NathanLovato]

I'll triage issues following this audit. Thanks for bringing these up. GDNative definitely has its place in Scripting. It's also a tool to bind third-party libraries so it feels it can be related to plugins. But it feels its main intended use is to allow you to code your game in different languages so scripting makes sense. I'll update the first issue.

[menip]

@menip thanks much for the feedback. I'm adding this to the first issue. Would you be ok if we copied some content from your documents? I see they're MIT-licensed. We'd mark you as the commit author or co-author, of cours

@NathanLovato That is perfectly fine by me.

[akien-mga]

Amazing proposal :+1:

I agree with the vast majority of the points listed in the OP, so I will only comment about those where I have something to add, but my general comment to all items is that it's good to go.

dockers

Note that we call those docks (or panels) in the current Godot jargon. But we already discussed this a couple of years ago ;)

Project workflow: move to Manual. I'm not sure about this section. I'd move its subsections up, e.g., there's quite a bit in Export (building the game for various platforms) and Best practices. And they're not exactly workflow to me.

Agreed, this has been used a kind of meta-section for things which everyone needs to know for any Godot project (assets workflow and how to export a game), and then Best practices were also added there, which are definitely not "Getting started" material.

So I agree that they should all be moved to Manual and made their own sections. For assets import/export, this is typically called "Assets pipeline", but if you think that's not clear enough, "Importing and exporting assets" might work (though it's tricky as you don't really export assets in Godot - you export them in Blender to import them in Godot).

The Exporting subsection definitely needs to stand on its own as a top-level section.

There are more sub-sections I'd like to remove by moving their content, like "Viewports", whose name may not be meaningful to some readers. For instance, we could have a section dedicated to rendering instead. That section could cover canvas layers, drawing, viewports, and more.

I tend to agree, though keep in mind that "Viewports" here is not just meant as a reference for the Viewport node, but how to configure the (root) viewport which is your game window (and which BTW in 4.0 is now an instance of Window). A viewport is the part of the screen used by the game's content.

I'm just mentioning this for context, not necessarily to imply that something else should be done that what is suggested.

3D Missing: Movement in 3D, the counterpart to the 2D article. Giving some good code examples for simple 3D movement.

Note that there's a risk of overlap between the 2D/3D sections and the Physics section, as movement is typically done using PhysicsBodies like RigidBody3D or KinematicBody2D. So we need to find the right balance between the two and do the cross-references that are meaningful (e.g. in the 2D/3D section talk about movement via the transform - position/translation, rotation, scaling - and link to the PhysicsBody docs for movement of physics characters).

Physics

Linked to the previous comment, we should make sure that there's clear documentation on all types of PhysicsBodies, and how to use them. It might make sense IMO to have a dedicated page for each class (e.g. in 2D: Area2D, KinematicBody2D, RigidBody2D, StaticBody2D, and possibly VehicleBody2D), and a global "Physics bodies (2D)" introduction page that puts them all in the big picture and includes the relevant links.

There's also the question of whether 2D and 3D physics should be split into separate sections, or if we can find enough shared aspects to have some common pages.

Missing: Navigation and AI

IMO the suggested sections are all Navigation, I'm not sure I'd mention AI which is a much broader concept than just pathfinding (and might lead to expectations of us documenting a lot more topics about AI, which IMO can be quite tricky as AI is always very game-specific beyond things like navigation and pathfinding).

Animation

The page "Introduction to 2D animation features" is actually a manual for the AnimationPlayer, which is not 2D-specific. So maybe it needs a better name. (It does use 2D examples but IMO it should still be made into a dimension-agnostic page about the AnimationPlayer features.)

Internationalization

There's a lot of new content from @SkyLucilfer following his GSoC 2020 work (currently in pending PRs that I have to review). Once those are merged, there might still be a need for refactoring the section a bit to be better focused (TBD, depends on how much @SkyLucilfer changed existing content or not).

GUI Missing: Overview of Godot's UI system and framework.

Indeed. BTW, one of the most frequent complaint we get around the class reference (notably users who are not satisfied enough by us focusing on the manual right now...) is that they expect to find full usage instruction in the class reference for each Control node.

I don't think that's the purpose of a class reference (and we probably need a documentation page that explains what the class reference is and how to use it - e.g. understanding that the documentation page for a given node is a superset of that of all of its parent nodes, which should therefore also be consulted if you search for how to use a feature common to several nodes), but that's definitely something that should be done in the manual. I.e. we should aim to cover the usage (in the editor) of all Control nodes.

GUI Missing: Best practices to design user interfaces in Godot: creating small, reusable components and using aggregation.

Note that if we have a Best practices section, maybe such page should go in that section instead of GUI.

Viewports Multiple Resolutions is a general topic that about every user will want to read. It's not directly related to the viewport node; instead, it's mostly about the window project settings. To me, this is related to "setting up your Godot project."

True, but we do need proper documentation that covers recommended strategies to make a game supporting multiple resolutions (especially in terms of UI) beyond the viewport settings like stretching. Currently that seems to be lacking (might be relevant to have in the GUI section).

Networking Feedback from @menip: had a bad experience getting started with networking in Godot, following the docs. This needs investigation. He wrote MIT-licensed tutorials and a general overview here: https://gitlab.com/menip/godot-multiplayer-tutorials/-/blob/master/NetworkingBasics.md

Maybe @Faless can have a look and give his opinion on how networking docs should evolve.

VR I need feedback from people who develop VR and AR games.

CC @m4gr3d @BastiaanOlij who have discussed it at length recently for the VR roadmap.

The current pages do follow the "step by step tutorial" approach that we're trying to avoid, which is mainly due to Bastiaan's hands on teaching style. It's not bad per se IMO but it does need some review in the context of this general audit to ensure consistency with the rest of the docs.

Plugins Platform-specific

I think Android plugins documentation might be worth moving under Platform-specific. There's a need for more documentation about iOS plugins/modules and specific features.

Debug

The current pages are descriptions of the editor panels for debugging. I'm a bit conflicted about whether this should be its own section or move into other ones for each specific tool, as suggested (Scripting, Performance, Rendering, etc.).

I think that what might be needed is a page that gives an introduction to all the main editor docks and plugins, with a screenshot and a brief description, and that links to the pages that review them in-depth in their relevant topical section. That would let users know at a glance what is what, how it's named, and more importantly, that it exists :) Many experienced users don't know about the existence of plugins like the ItemList editor plugin, or the Polygon2D editor plugin, to name a few. (Editor plugin is the name of those classes internally in the editor code, but it's up for discussion whether they should be presented to users under those names or with a different name. For example the "2D viewport" is called CanvasItemEditorPlugin.)

I removed the two addressed issues from the audit. Please don't create individual PRs for tiny changes, as that's making it more work than it needs to be.

I disagree. I think we should systematically use PRs, even for tiny changes. That's the workflow that we ask of contributors with Write permissions and I think core developers should follow the same rules (which is also what we now do on the main engine repo).

On the other hand it's completely fine to open a PR for a tiny change and merge it yourself once CI passes. We've improved the CI greatly and it should now be quite fast, but it's important to have it run still.

Opening PRs for all changes helps ensure that contributors are aware of the changes being done. This was the main motivation for going with a Git repo over something like e.g. MediaWiki, as reviewing changesets in a wiki where anyone can edit anything is a major time sink, while with a PR workflow you have an easy way to keep track of all changes. (Especially if you're subscribed to notifications from this repo, as I am.)

[NathanLovato]

Thanks for the detailed feedback @akien-mga. Agreed with everything. I'll update the audit based on your notes and only reply to the parts that need precision.

There's also the question of whether 2D and 3D physics should be split into separate sections

Either into two sections or, because there's not going to be as much content there compared to 2D and 3D, we can organize the articles inside the section, like the new Optimization section that has a neat table of contents with titles.

I'm fine with either.

IMO the suggested sections are all Navigation, I'm not sure I'd mention AI

Navigation is fine by me too. I think quite a few users think of pathfinding, line of sight, and things like these as being AI, hence the suggested name.

I disagree. I think we should systematically use PRs, even for tiny changes.

I think you misread. The point was about making one PR with 4 commits instead of 4 separate PRs each renaming a different page's title:

If you'd like to tackle small tweaks like renaming a page, please bundle them together. Even if you make multiple commits as part of one PR.

[akien-mga]

I think you misread. The point was about making one PR with 4 commits instead of 4 separate PRs each renaming a different page's title:

If you'd like to tackle small tweaks like renaming a page, please bundle them together. Even if you make multiple commits as part of one PR.

Right, I agree with that second part about grouping simple changes in a single PR. But I was also reacting to this:

Note that when a change doesn't need review, you can commit directly without opening a PR. E.g. for the CSG page title.

[NathanLovato]

Ah sure, I take it back then.

[BastiaanOlij]

@NathanLovato ping me in the evening or weekend if we're both online and we can have a bit of a discussion about Vehicle physics and XR documentation so you can flesh out what needs more attention there.

[NathanLovato]

The audit accepted, I'm now preparing to create individual issues from it. Closing as a result.