v6-docs
v6-docs copied to clipboard
adonisjs
New structure proposal
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
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.
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.
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!
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
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.
+1 for me, I think is a great change! I think one thing we are missing as a community is more example projects.
+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.
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.
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
@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
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.
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
If we do that, we are splitting the content again, which I want to avoid. What are your goals with this change?
better readability and discoverability, avoiding put too much content in a single page.
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.
Something like: https://docs.strapi.io/dev-docs/quick-start https://nextjs.org/learn/dashboard-app
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.
We got an internal discussion today, here is the latest feedback and final structure we will use.
- We are going to merge
AdonisJS ConceptsandArchitecture Concepts - Rename
Request LifecycletoHttp Overview - We keep the
Bodyparsersection outside ofRequests - We don't merge
Assets BundlingandStatic File Server - We rename
Assets BundlingtoVite - We move the
Internalssection toConcepts - We move
Extending the frameworktoConcepts - We move
RepltoDigging 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
Yup, looks good.
A few things to note.
User Credentialsshould beVerifying user credentialsbecause the term "User Credentials" does not convey anything.Release Notesshould beReleasesbecause we list the releases only here, and the notes are on Github.TypeScript Buildshould beTypeScript build processto 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 Commandsin 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.
This is amazing work! Well done, much respect 🙏 I believe the final version is much clearer than the previous docs.
👋🏻
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
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/
