New structure proposal

[RomainLanz]

Hey there! 👋🏻

As discussed internally with the core team, I want to revamp how the documentation is structured.

I mainly took example on an internal proposal I made for AdonisJS 3 documentation, current AdonisJS 4 and 5 documentation and Laravel documentation.

The end goal is to have something simple for newcomers to go through, and even for recurring users without loosing any content. I believe we split a bit too much some information across many pages, so I merged a few sections together (like we had in AdonisJS 5 documentation)

A complete structure can be found at the end of this message.

On a side note, this structure has been made during a live stream in front of ~100 people. They also gave feedback and thought to build this new structure.

This proposal will go through each section, point by point, explaining its content and its goal.

Legend:

• (From: *) - If the name has been changed, this will contain the old name OR it help to distinguish the content if we have the same name multiple time
• (+ *) - We are merging content
• (New) - New content we have to write
• (~New) - New content we have to gather from other pages
• (PR) - New content with a PR
• (Previously: *) - Proposal for a rename
• (?) - Not sure if needed here

---

Preface
├── Introduction (From: Getting Started - Introduction)
├── FAQ
├── Governance
├── Release Notes
└── Contribution Guide

This section is ordered in a logical way.

The goal of this section is to provide all "meta" information about the framework. Its philosophy, faq, governance status, etc.

---

Getting Started
├── Installation (From: Getting Started - Installation)
├── Configuration
├── Environment Variables
├── Folder Structure
└── Deployment (From: AdonisJS 4 - Deployment)

This section is ordered in a logical way.

The goal of this section is to have a Zero to Production information for a minimum setup. I believe all sub-sections are needed to have a minimum understanding of all the defaults boilerplate.

---

AdonisJS Concepts
├── Application
├── Application Lifecycle
├── Config Providers
├── RC Files
├── Service Container
└── Scaffolding

This section is ordered by alphabetical order.

The goal of this section is to explain concepts linked to AdonisJS and how we structured our and the application code.

---

Architecture Concepts
├── Async Local Storage
├── Dependency Injection (Previously: IoC Container )
├── HMR (PR)
├── Http Context
├── Request Lifecycle (From: HTTP - Introduction)
└── Service Providers

This section is ordered by alphabetical order.

The goal of this section is to explain common architectural concepts we may found in other frameworks.

---

Basics
├── Routing (+ URL Building)
├── Controllers
├── Middleware
├── Requests (+ BodyParser middleware)
├── Response
├── Validation
├── File Upload
├── Session
├── Cookies
├── Exception Handling
└── Static Assets (Assets bundling + Static server)

This section is ordered in a logical way.

The goal of this section is to contain anything relative for building simple project. Nearly all of those features are needed for a standard SSR application.

---

Database
├── Introduction (~New - From: SQL and ORMs)
├── Lucid ORM (~New - From: SQL and ORMs)
└── Redis

This section is ordered in a logical way.

The goal of this section is to contain anything related to database you may want to use with AdonisJS. In the feature, we may add Kysely or Prisma there for example.

---

Authentication
├── Introduction (From: Authentication - Introduction)
├── User Providers (+ Verifying user credentials)
├── Auth Guards (+ all the guards doc)
└── Social Authentication

This section is ordered in a logical way.

Another proposal for this section would be to keep all the auth guard separated:

├── Session Guard
├── Access Token Guard
├── Basic Auth Guard
├── Custom Auth Guard

The goal of this section is to contain anything related to authentication.

---

Security
├── Introduction (New)
├── Authorization
├── Encryption
├── Hashing
├── Signed URLs (?)
├── Web Security (+ CORS + Securing SSR apps)
└── Rate Limiting

This section is ordered in a logical way.

The goal of this section is to contain anything related to securing an application.

---

Views & Templates
├── Introduction (~New - From:  HTTP - Views and Templates)
├── EdgeJS (~New - From:  HTTP - Views and Templates)
└── InertiaJS (From: Experimental - InertiaJS)

This section is ordered in a logical way.

The goal of this section is to contain anything related to views and templates. We may add TSX or KitaJS in the future in this section.

---

Testing
├── Introduction
├── Http Tests
├── Browser Tests
├── Console Tests
├── Database
└── Mocks & Fakes

This section is ordered in a logical way.

The goal of this section is to contain anything related to testing. No real change from what we have right now.

---

Digging Deeper
├── Ace Commands (+merge all doc)
├── Caching (New)
├── Emitter
├── I18n
├── Locks
├── Logger
├── Mail (+merge all doc)
├── Transmit (PR)
└── Extending the framework

This section is ordered by alphabetical order except the last point.

The goal of this section is to contain anything that is less used than the Basic section to make an application. The goal is keep one page per feature.

Also, Ace Commands will probably move to its own website.

---

API References
└── NO CHANGE

No change for this section.

---

Internals
├── Tooling Config
└── TypeScript Build

This section is ordered by alphabetical order.

The goal of this section is to contain anything not directly related to people's application. Internal process.

---

Experimentals
└── NO CHANGE

No change for this section.

---

FINAL SIDEBAR

Preface
├── Introduction
├── FAQ
├── Governance
├── Release Notes
└── Contribution Guide

Getting Started
├── Installation
├── Configuration
├── Environment Variables
├── Folder Structure
└── Deployment

AdonisJS Concepts
├── Application
├── Application Lifecycle
├── Config Providers
├── RC Files
├── Service Container
└── Scaffolding

Architecture Concepts
├── Async Local Storage
├── Dependency Injection
├── HMR
├── Http Context
├── Request Lifecycle
└── Service Providers

Basics
├── Routing
├── Controllers
├── Middleware
├── Requests
├── Response
├── Validation
├── File Upload
├── Session
├── Cookies
├── Exception Handling
└── Static Assets

Database
├── Introduction
├── Lucid ORM
└── Redis

Authentication
├── Introduction
├── User Providers
├── Auth Guards
└── Social Authentication

Security
├── Introduction
├── Authorization
├── Encryption
├── Hashing
├── Signed URLs
├── Web Security
└── Rate Limiting

Views & Templates
├── Introduction
├── EdgeJS
└── InertiaJS

Testing
├── Introduction
├── Http Tests
├── Browser Tests
├── Console Tests
├── Database
└── Mocks & Fakes

Digging Deeper
├── Ace Commands
├── Caching
├── Emitter
├── I18n
├── Locks
├── Logger
├── Mail
├── Transmit
└── Extending the framework

API References
└── NO CHANGE

Internals
├── Tooling Config
└── TypeScript Build

Experimentals
└── NO CHANGE

[Barbapapazes]

What a great improvement! I'm pleased to see this proposal!

For the HMR page, I'd rather see it in the internal tooling section more than in the architecture concept since it's just a flag with the serve command and this does not impact how the dev will use Adonis.

[RomainLanz]

For the HMR page, I'd rather see it in the internal tooling section more than in the architecture concept since it's just a flag with the serve command and this does not impact how the dev will use Adonis.

I place it here because it is a concept linked to Node.js (not AdonisJS). However, it could also go inside the Internal section since it is not something someone has to know.

[Barbapapazes]

Extending the framework could be a separate section since this could cover extentions for a module like the HTTP request, Vine, a new social auth AND having a page dedicated to how dev can create externals and sharables modules.

Customization is one of the strength of the framework and it should really be highlighted in the nav!

[tpoisseau]

SGTM, I suggest to separate Auth Guards in to sub-pages

Authentication
├── Auth Guards # generic information about auth guards, how to apply, and name them.
    ├── Session Guard
    ├── Access Token Guard
    ├── Basic Auth Guard
    ├── Custom Auth Guard

[RomainLanz]

SGTM, I suggest to separate Auth Guards in to sub-pages

Authentication
├── Auth Guards # generic information about auth guards, how to apply, and name them.
    ├── Session Guard
    ├── Access Token Guard
    ├── Basic Auth Guard
    ├── Custom Auth Guard

Do you mean the second proposal or to have a third level in the sidebar? Because you mixed the two in your message.

First Proposal: merge all guard documentation under the same page Auth Guards

Authentication
├── Introduction
├── User Providers
├── Auth Guards
└── Social Authentication

Second Proposal: keep the guard documentation separated on their own page

Authentication
├── Introduction
├── User Providers
├── Session Guard
├── Access Token Guard
├── Basic Auth Guard
├── Custom Auth Guard
└── Social Authentication

The goal was to replicate a schema I showed during meetup/talk.

[britzdylan]

+1 for me, I think is a great change! I think one thing we are missing as a community is more example projects.

[RomainLanz]

+1 for me, I think is a great change! I think one thing we are missing as a community is more example projects.

This is planned as part of our "Bootcamp" project.

[bitkidd]

Nice one! The only thing I would change: Preface -> General. Feels like the word “General” gives a little bit more freedom to put inside it something more general about the framework. And I would not shy off from adding “Donations” section into it.

[Mizux]

nit: in

Preface
├── Introduction (From: Getting Started - Introduction)
├── FAQ
├── Governance
├── Release Notes
└── Contribution Guide

I would put FAQ and Release Notes closer (imho something not in the release note should be in the FAQ and vice versa) while Contribution Guide should follow the Governance (gouvernance could impact the contrib policy imho)

Proposal

Preface
├── Introduction (From: Getting Started - Introduction)
├── FAQ
├── Release Notes
├── Contribution Guide
└── Governance

[Foysal50x]

This is really cool 👍 1+ for me

[tpoisseau]

@RomainLanz

Do you mean the second proposal or to have a third level in the sidebar? Because you mixed the two in your message.

I mean have a third level in the sidebar

[RomainLanz]

@RomainLanz

Do you mean the second proposal or to have a third level in the sidebar? Because you mixed the two in your message.

I mean have a third level in the sidebar

In my opinion, that will clutter the sidebar too much and it is not currently doable in our documentation software.

[tpoisseau]

What do you think about make an "Auth Guards" or "Authentication Guards" section ?

Authentication
├── Introduction
├── User Providers
└── Social Authentication

Auth Guards
├── Introduction
├── Session Guard
├── Access Token Guard
├── Basic Auth Guard
└── Custom Auth Guard

[RomainLanz]

If we do that, we are splitting the content again, which I want to avoid. What are your goals with this change?

[tpoisseau]

better readability and discoverability, avoiding put too much content in a single page.

[ShahriarKh]

I think a section like tutorial or recipes will be great for newcomers. The current docs is more of an API reference, and if you want to implement something in your app, you have to watch videos (which are great, but doesn't cover cases where you need a quick look or prefer text content) or dig the docs and connect the puzzle pieces by yourself.

[ShahriarKh]

Something like: https://docs.strapi.io/dev-docs/quick-start https://nextjs.org/learn/dashboard-app

[RomainLanz]

better readability and discoverability, avoiding put too much content in a single page.

Then you want the second solution. Otherwise, we are cluttering the sidebar too much, and people will be lost with too much section.

Also, having more content on the same page has never been an issue. It allows you to easily search and avoid switching back and forth on multiple pages. You want to learn about "Auth Guard"? Go to the "Auth Guard" section and start to read from here.

For example, this is done in AdonisJS 5 or Laravel for the Mail section, and it was fine.

I think a section like tutorial or recipes will be great for newcomers. The current docs is more of an API reference, and if you want to implement something in your app, you have to watch videos (which are great, but doesn't cover cases where you need a quick look or prefer text content) or dig the docs and connect the puzzle pieces by yourself.

This is not the goal of the documentation and is already planned in the Bootcamp project.

The documentation will not teach you how to build an app from scratch. For that, we plan to write step-by-step tutorials that teach you how to build a specific app using the framework.

• What to Expect of AdonisJS 6?

[RomainLanz]

We got an internal discussion today, here is the latest feedback and final structure we will use.

• We are going to merge AdonisJS Concepts and Architecture Concepts
• Rename Request Lifecycle to Http Overview
• We keep the Bodyparser section outside of Requests
• We don't merge Assets Bundling and Static File Server
• We renameAssets Bundling to Vite
• We move the Internals section to Concepts
• We move Extending the framework to Concepts
• We move Repl to Digging Deeper

Final structure:

Preface
├── Introduction
├── FAQ
├── Governance
├── Release Notes
└── Contribution Guide

Getting Started
├── Installation
├── Configuration
├── Environment Variables
├── Folder Structure
└── Deployment

Concepts
├── Async Local Storage
├── Application
├── Application Lifecycle
├── Config Providers
├── Container Services
├── Dependency Injection
├── Extending the framework
├── HMR
├── Http Overview
├── Http Context
├── RC Files
├── Service Providers
├── Scaffolding
├── Tooling Config
└── TypeScript Build

Basics
├── Routing
├── Controllers
├── Middleware
├── Bodyparser
├── Requests
├── Response
├── Validation
├── File Upload
├── Session
├── Cookies
├── Exception Handling
├── Vite
└── Static Assets

Database
├── Introduction
├── Lucid ORM
└── Redis

Authentication
├── Introduction
├── User Credentials
├── Session Guard
├── Access Token Guard
├── Basic Auth Guard
├── Custom Auth Guard
└── Social Authentication

Security
├── Introduction
├── Authorization
├── Encryption
├── Hashing
├── Signed URLs
├── Web Security
└── Rate Limiting

Views & Templates
├── Introduction
├── EdgeJS
└── InertiaJS

Testing
├── Introduction
├── Http Tests
├── Browser Tests
├── Console Tests
├── Database
└── Mocks & Fakes

Digging Deeper
├── Ace Commands
├── Caching
├── Emitter
├── I18n
├── Locks
├── Logger
├── Mail
├── Transmit
└── Repl

Ace Commands
└── NO CHANGE

API References
└── NO CHANGE

Experimentals
└── NO CHANGE

[thetutlage]

Yup, looks good.

A few things to note.

• User Credentials should be Verifying user credentials because the term "User Credentials" does not convey anything.
• Release Notes should be Releases because we list the releases only here, and the notes are on Github.
• TypeScript Build should be TypeScript build process to complete the sentence.
• In security, we are missing CORS.
• Again, I prefer "Securing SSR apps" over "Web security". Aligns more with the intent of the doc.
• There won't be Ace Commands in digging deeper for now. Until we move Ace docs to its own website.

Also, I noticed that you went with "Title case" in all the topic names. However, currently, the documentation follows the "Sentence case". There is nothing wrong with either of those. Even from the English point of view, both are technically correct. But for consistency, we should stick with "Sentence case."

Finally, once we move content around. We should double-check:

• If any URLs are changing and must define redirects for them.
• Also, update internal links if the content files are moved to different folders. Right now, the links are resolved from the location of the file.

[aarhusgregersen]

This is amazing work! Well done, much respect 🙏 I believe the final version is much clearer than the previous docs.

[RomainLanz]

👋🏻

You are invited to give your feedback on the PR: https://github.com/adonisjs/v6-docs/pull/86

You can see the changes there: https://feat-new-structure.v6-docs.pages.dev/guides/preface/introduction

[SteveSimms]

Something like:

https://docs.strapi.io/dev-docs/quick-start

https://nextjs.org/learn/dashboard-app

I agree with this. Something like the laravel bootcamp would be super helpful for new comers to get up and running.

https://bootcamp.laravel.com/

[RomainLanz]

Closing since the changes have been applied.