Godot-docs: Docs structure improvements

[mhilbrunner]

The current docs structure is getting a little hard to browse and discover as we get more content.
In particular, the Engine features section contains a lot of the meat of the docs, but is fairly hidden and opaque to a new user.

I suggest changing the current structure:

• Learning
  
  
  
  • Step by step
  
  
  • Editor manual
  
  
  • Engine features
  
  
  • 2D
  
  
  • 3D
  
  

By renaming "Learning" to "Getting Started" and moving "Engine features" one layer up and renaming it to "Tutorials", so the above becomes:

• Getting Started
  
  
  
  • Step by step
  
  
  • Editor manual
  
  
• Tutorials
  
  
  
  • 2D
  
  
  • 3D
  
  

[mhilbrunner]

@godotengine/documentation @reduz please have a look, esp. akien and reduz :)

[NathanLovato]

I second the idea. I'd bet that the engine features section doesn't get as many clicks as it should as it reads like list of available features in the engine. Note that in the docs, the section titles barely read and it's mostly the category names you see in the sidebar.

Also considering Godot's docs aren't your typical austere, reference-like manual, the word Tutorials makes sense for me - it's the one keyword most beginners will search for. Many categories contain tutorials, and there are more to come. Step by step is a tutorial series.

Not 100% sure about the naming but all the categories like 2D, 3D etc. are super important and should be top-level. Then we could move some tutorials away from step-by-step to the categories they belong (animation, UI, physics etc.)

[cbscribe]

Agreed. Now is the time to do this - we just need to agree on the actual naming.

• Changing "Step by step" to "Intro" -> I would use the full word "Introduction" or better: "Getting Started", which is a very common heading in a lot of technical manuals. Users will know what to expect from that.

• "Tutorials" is a better title. This is primarily what people are searching/asking for. I suspect Nathan's right that nobody clicks on "Engine Features" expecting to find how to do things.

[mhilbrunner]

@cbscribe Think "Getting Started" is better, updated the issue to reflect it as a suggestion.

[NathanLovato]

Yeah looks it sounds right now. Getting Started and Tutorials, it's attractive and informative at the same time

[akien-mga]

Keep in mind that the first level (actually, those are not first levels but different tables of content: https://raw.githubusercontent.com/godotengine/godot-docs/master/index.rst ) is not clickable, so you can't link to e.g. "Tutorials" in your proposal.

That's why we went for the current structure after thinking it through a lot with @StraToN.

[StraToN]

To me, a tutorial is a complete "how-to-achieve-this-result", which probably covers multiple features, not only one. We chose to name the section "Engine features" because the pages in this section are supposed to describe the use of one engine feature at the time. If we create a "Make an RPG in Godot" tutorial, I think we indeed require a "Tutorials" section.

For example, "How to create a shoot'em-up" is a tutorial (according to this definition) because it certainly uses multiple engine features.
And "How to use AnimatedSprite" is the explanation of only one engine feature.

I agree that "Engine features" is probably not a very good name, though. We could think of another.

[mhilbrunner]

The main thing for discoverability is moving the section up in the hierarchy. Suggestions for a better name besides "Tutorials"? "Topics"?

[NathanLovato]

Keep in mind that the first level is not clickable

That shouldn't be a problem. By default, now, you won't see what's under "engine features" while it has all the categories you're looking for in a manual.

If I'm making a 2d game, I'm looking for the 2d category. If I'm struggling with animation... The idea is to always have them visible at a glance from anywhere in the docs because they're essential.

To me, a tutorial [...] probably covers multiple features, not only one

A tutorial is a guide to reach a certain goal, e.g. How to use AnimatedSprite. You're free to scope it however you'd like. It's not about learning to do a lot of things at once.

Initially it meant a guide made by a tutor. The idea was for it to feel like someone was teaching/mentoring you one-on-one. And in general it relates more to practical training than theory although it's become a catch-all phrase.

So to me tutorial describes the current engine features section a lot better considering its content.

But the important part here is it's the keyword people look for the most when they want to learn to do something. Tutorials are seen as more accessible than the concept or a reference or a manual. And software manuals are so difficult to digest in general (especially in foss programs) you can see why.

[NathanLovato]

It's something I've learned from Youtube: the way you name your videos (along with the thumbnails) is just as important as the content to get people to click. If it sounds like it's what people want and it looks like what people want, it's what people want ;)

[NathanLovato]

Btw the current organization is a great improvement over what the docs were like before. @mhilbrunner is just suggesting a tweak to help increase the discoverability of what should be core categories and browsing experience a little more.

[Omicron666]

What about "HOW TO" section ?

[mhilbrunner]

IMO, we should use the "Community -> Tutorials" section for tutorials with scopes like "How to make an RPG in Godot". Because I think those should be out of scope for the "official" docs - they will be too long and too involved for us to have any chance to maintain them with time. Again, IMO.

So I think "Tutorials" will be fine for the renamed section (formerly "Engine features").

And yeah, sorry if it came off that way, I'm not saying that the current structure is bad, only that I think it could maybe be improved further :)

[StraToN]

@NathanLovato

A tutorial is a guide to reach a certain goal, e.g. How to use AnimatedSprite. You're free to scope it however you'd like. It's not about learning to do a lot of things at once.

Ultimately, yes you are right.

Actually, it would probably be better to say that when @akien-mga and I reorganized the documentation, we could not really say that a given page was a tutorial or not - we could only estimate its purpose. I may be wrong, but as a newcomer I was first looking for each node's documentation (not speaking of API here). The reason is that certain nodes can be used in different ways and I needed to know in which cases. My main problem is that having this specific explanation "drown" into a big tutorial that explains tons of (surely) interesting stuff is not what I'd've wanted. That's why I find interesting to keep some small pages that describe only one topic - and that's why I don't like to call them tutorials.

Also, certain nodes come with a specific tool panel in the editor (AnimationPlayer, AnimatedSprite, ResourcePreloader, etc) and that is the purpose of "Editor manual" section.

Finally, a lot of nodes are self-explanatory and no not require further docs. If they do, users will let us know for sure ;)

[mhilbrunner]

@StraToN FWIW, these are the only things currently located in "Editor manual":

• 2D and 3D keybindings
• From Unity3D to Godot Engine
• Command line tutorial

[StraToN]

@mhilbrunner Yep. This section is supposed to contain future pages, specific to the editor such as:

• Integrated debugger usage
• AnimationPlayer tool usage
• Import panel
• ResourcePreloader panel
  etc

[akien-mga]

Keep in mind that the first level is not clickable

That shouldn't be a problem. By default, now, you won't see what's under "engine features" while it has all the categories you're looking for in a manual.

If I'm making a 2d game, I'm looking for the 2d category. If I'm struggling with animation... The idea is to always have them visible at a glance from anywhere in the docs because they're essential.

Fair enough. I'm fine with a change along those lines then, and I trust you guys to settle on the best layout -- I won't have much time to work on it or even discuss it myself.

This needs to happen before the 3.0 release/branching, so ideally in the coming 2-3 days. Folders/pages should be moved accordingly in git to properly reflect the new structure (toctree and URLs -- the latter based on directory structure -- should be synchronized).

And redirects will be needed for those pages that were moved to prevent getting 404s for the next couple of months while search engine indexes are updated. @NathanLovato Would you create an account on https://readthedocs.org/projects/godot/ so that I can add you as admin for the project?

[hubbyist]

Then we could move some tutorials away from step-by-step to the categories they belong (animation, UI, physics etc.)

I think stripping down step-by-step section by moving tutorials from it will not be an improvement. Step-by-step section is the most welcoming part of the documentation in its current state. At least first tutorial of each engine feature must be there to give a complete picture of what can be achieved with godot to a newcomer.

[NathanLovato]

first tutorial of each engine feature must be there to give a complete picture of what can be achieved with godot to a newcomer.

I see your point, but this would make for an overwhelming... 40-50 tutorials long series? Getting started/step-by-step is meant to be a short, linear and general introduction to Godot. There are so many features in Godot that if you show all the complexity from the start you scare beginners away. Plus some people will want to do 2d only, others 3d only, some mobile only, etc.

Once we changed the menu's layout, we can redirect people to specific categories where they can learn more about the topics they're interested in or struggling with, knowing that everything will be tutorials.

BTW I wasn't talking about all tuts but e.g. there are 4 UI pages in step-by-step, and it's neither super beginner-friendly nor necessary to get started making your games.

[NathanLovato]

@mhilbrunner Do you have time to do it in the next few days or should I take care of it?

[ZX-WT]

@NathanLovato
I know you are working on it and it is a bit late to give an extra suggestion but I sill want to express it.
Can we eliminate the miscellaneous section? is it possible to better categorize it? as now the structure is more obvious, IMO, the misc part is not that direct.

[NathanLovato]

@ZX-WT Yeah just finished it. Please open a new issue with a proposal. Each page in misc needs to end up somewhere else.