My first suggestion is: why not swap this part with Getting Started, which is more useful to get new people on the ride? Plus it’s not illogical to want to know more about the doc after do first bits of code.
Second suggestion is about the fact that it’s an image without, by definition, clickable links: replacing the image by a table could be interesting also.
The current landing page is way too much text for an intro screen. I would prefer to be presented with an index of some sort. When people want to see the docs, I think mainly they want to go to the API reference. Your suggestion of cutting straight to “Getting Started” is better than the information overload that is currently there, but when somebody’s goal is “show me the documents”, I think putting a table of contents or some kind of index in front of them is more useful. The “HowTo” could be a possibility as well.
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!
Good points. So maybe the example of Unity doc welcome page is a good one: all sections are available and illustrated, even “what’s new” & “best practice” are suggested.
(maybe even for some devs).
adding