Documentation structure

[rockymontana]

We talked on the discord about how the documentation could use some love.

And what I think Laravel for example does really well in their documentation is that they try to see it from the eyes of someone that have never used their framework before. Instead of writing it from the technical components that builds up the framework, they structure it as a kind of journey for the newcomer.

If we think from the perspective that I visit the site for the first time and I read the documentation to get an idea of what it is, would I understand what an Adonis module is? I would say maybe, but probably not.
I would probably have to know about it beforehand and have at least a slight idea on how to work with it.
Maybe it would be an idea to start with the concept how it's built up.

After that I, as the first time visitor, need to know how to get started with a new project.
And then when I understand the concept, it's easier for me to dig into the fundamentals about how I use it. Where do I begin? I need to start understanding how to work with the framework without the requirement of me understand in which layer each part exists.
My very novice guess is that most people use adonis to build web stuff. If so, the HTTP category might not be necessary, but rather take me (again - the first time user) through the steps on how to get started with that via some kind of Getting Started Introduction that showcases how you'd hello world in adonis, and then build on top of that.

Menu example for that could be:

{
    title: "Getting Started",
    menuItems: [
        { 
            title: "Introduction",
            menuItems: [
                { title: "Installation" }, // Covering type of application (web/api) etc
                { title: "Application" }, 
                { title: "AdonisRC file" }, 
                { title: "TypeScript build process" },
                { title: "Deployment" }, 
            ]
        }, 
        { 
            title: "Config",
            menuItems: [
                { title: "Environment variables" }
            ]
        }, 
        { title: "Routing" },
        { title: "Controller" },
        { title: "Requests" },
        { title: "Responses" },
        { 
            title: "Models",
            menuItems: [
                { title: "ORM" },
                { title: "Relationships" },
            ]
        },
        { 
            title: "Views",
            menuItems: [
                { title: "Edge" },
            ]
        }
    ]
}

By the time I've finished that part of my learning journey I should be good to understand more complicated topics such as Ace Commands, Package development, Testing etc.

So all in all, I don't say that the actual content is bad, but I do think that the experience for users going through the docs could be improved.

[Barbapapazes]

Hello,

The docs is actually awesome but I agree that for newcomers, it could be very disturbing to know how to use Adonis and to start with it

Do you think that Adonis could use the same organization that Laravel use?

[rockymontana]

Yeah, the content is great. Not saying anything about that.
What sticks out to me is that when I go read the docs about validation I get one portion of the documentation.
The Validation rules are some place else. You have to have knowledge about how to consume the docs to find the content you want to find. That same thing is true for more parts of the documentation iirc.

I think that Adonis could use the same type of structure and mindset at least. If not it's something to be inspired by.