New structure proposal about v6-docs HOT 22 OPEN

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

from v6-docs.

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!

from v6-docs.

+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.

from v6-docs.

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

from v6-docs.

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

from v6-docs.

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.

from v6-docs.

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.

from v6-docs.

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.

from v6-docs.

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.

from v6-docs.

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

from v6-docs.

This is really cool 👍 1+ for me

from v6-docs.

@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.

from v6-docs.

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

from v6-docs.

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?

from v6-docs.

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.

from v6-docs.

@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

from v6-docs.

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

from v6-docs.

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

from v6-docs.

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.

from v6-docs.

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

from v6-docs.

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

from v6-docs.

👋🏻

You are invited to give your feedback on the PR: #86

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

from v6-docs.