I love the thought process here.
Here’s my take.
Super high level we/I want the first place that people land in the documentation to be as accessible as possible to as many different types of people as possible. This means that we need it to be easy to understand, informative, and not at all intimidating. It should be something useful for developers, artists, tech artists, people with lots of experience, and people with no experience at all.
I agree that maybe starting right off the bat with how the docs are organized isn’t the best for getting people right into code, but it IS useful for people to understand where they should go for their first step. For someone who isn’t a developer, writing code may not be their first step right? Perhaps Babylon 101 is the most useful first place they should go. Or perhaps just looking at examples that others have written to get in idea of what’s possible. The point is we don’t necessarily know what each person is going to want for their “First Step.”
What ya’ll are raising here is awesome…we should definitely rethink the first thing people see, but I’m not sure presenting people with the API or getting them right into code is the perfect answer. Not dismissing the idea at all, but I’d bet there’s a better way to let the “Getting Started” section be more of a “choose your own adventure” than it is now.
Picture something like this:
Everyone comes to a documentation landing page…something visual and well organized (not too much text per @Joseph_DeStefano’s comment), but something that can EASILY help you get to where you want to be…something with links (like @Vinc3r’s second suggestion). Then everyone is one simple click away from what they each individually want/need. We’ve got the starting point of the main idea here with the visual image describing the different parts of the docs, but we need to improve on the execution.
In addition to that, It’s probably about the time where we should ask ourselves if the organization of all of the information is as good as it could be. This is something that’s been on my mind for a while…something I want to dive into and revisit with the community…that said, it’ll have to wait until after the 4.1 release. Heads down until then!
Love all of the enthusiasm and suggestions on the docs everyone! Keep it coming!
(maybe even for some devs).
adding