Suggestion for restructuring the docs

[ttencate]

After several months of working with Godot, the structure of the documentation is still confusing me. Everyone I've talked to about it says the same. Many things are actually there, but not in the place where people would expect them to be.

Here's the top-level sections that I would expect:

• GENERAL: similar to what it is now. What is Godot, what is it not, how did it come to be, FAQ.

  • Introduction
  • Godot's design philosophy (moved from "Getting Started")
  • FAQ

• GETTING STARTED: installation, explanation of high-level concepts that are used throughout the engine, like nodes, scenes and resources. Maybe a tutorial or two. Moving from Unity. Right now, there's much more here, and it's far too deeply buried.

  • Concepts: what is now "Step by step", minus the tutorials
    • Scenes and nodes
    • Instancing
    • ...
  • Your First Game: moved one level up
  • From Unity3D to Godot Engine

• TUTORIALS: step by step guide to achieve a specific result (click here, type this, press this button). Dodge The Creeps is an excellent example (though I placed it under Getting Started). Right now, the Tutorials section is full of reference-style material. This should be picked apart.

  • Scripting
  • Design a title screen
  • ...

• REFERENCE: explains specific concepts and features like animation and GUI in comprehensive detail. GDscript "specification" (such as it is). Also API docs.

  • GDscript: moved one level up from Scripting, because this is important and needs to be easy to find.
  • VisualScript
  • C#
  • 2D
  • 3D
  • Audio
  • ... most of what is now under "Tutorials", really.
  • API reference (or perhaps "Class reference", formerly "Godot API")

• DEVELOPMENT: contributing to the engine and its documentation.

  • Contributing
  • Compiling
  • Engine development
  • Godot file formats

• COMMUNITY: https://godotengine.org/ already has a heading with that name. Move content to there if possible, and remove this heading.

I don't know what thought process went into designing the current structure, so I might be missing important arguments for doing things the way they are done. In that case, please enlighten me, so we can arrive at a solution that's best for everyone :)

[CptPotato]

I think this is a very good idea/concept, though I guess it would also require a lot of work.

Personally, found the class reference the most troublesome to work with as it's not categorized and difficult to search.

[ttencate]

The class reference is a slightly different topic, because it's autogenerated. It could be structured better than a flat list, but let's focus this issue on the "regular" docs.

I think it could be done in a few hours of focused labour (famous last words) and if everyone agrees, I might be willing to do it (famous last words too...).

Has anyone from Godot docs team had time to read this yet?

[cbscribe]

This comes up now and again. See #1003, for example.

I'd be happy to review a pull request if someone wants to tackle it. I think it's more work than you think, but if you want to tackle it, I say go ahead and get the ball rolling. A PR is likely to create more action and response than a plain discussion.

BTW, how is the class reference difficult to search? Type the node or method you're looking for and the matches come up. See #346 for a previous discussion - since it's "consumed" by more than just the online docs, it's not a trivial task to reorganize. FWIW, I did most of my Godot learning using the API docs and found it relatively easy to find things, even in the pre-3.0 days when there was much less description coverage. Every class lists its inheritance, returned types are linked, etc. It works very well as a reference.

[NathanLovato]

There's been long discussions on that. The main suggestion I see here is to split tutorials and general guides in two.

The docs' structure is simple: past the getting started section, all areas of the engine have their own page and you can find everything you'd need about them there. Instead of having two sections, e.g., tutorials and reference, with duplicate names, because we'd need to categorize them: tutorials about physics, reference manual about physics, etc.

The way readthedocs works, it means you'd end up having this list two times over time, as people get to cover new features and add new tutorials.

The other reason to not rename the tutorials section was you'd need to redirect every page. It was enough of a pain last time we did so.

Sure, there's always room for improvement. If someone could go through every page in the docs and categorize them well, that'd be great. There's a lot of work involved.

[ttencate]

@cbscribe Thanks for chiming in. It seems #1003 resulted in significant improvement and more or less brought us to where we are today, so it makes for good background reading on why things are the way they are. I was hesitant to start on a PR without gathering any input and context beforehand, because it will be a fair bit of work.

@NathanLovato You make an excellent point about duplicating all the categories. I would have to see how many things under Tutorials really are tutorials. If it's just a handful, categories might not be needed, or could be a bit broader than those in the Reference section.

[akien-mga]

I'd be happy to review a pull request if someone wants to tackle it. I think it's more work than you think, but if you want to tackle it, I say go ahead and get the ball rolling. A PR is likely to create more action and response than a plain discussion.

No, please don't waste hours moving files around and fixing paths to make a PR. The structure should be decided first, then it should be PR'ed. A PR changing the docs structure would be unreadable anyway.

[NathanLovato]

Addressed by #3969, but also current and upcoming changes, closing for now