-
-
Notifications
You must be signed in to change notification settings - Fork 45
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New structure proposal #80
Comments
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. |
I place it here because it is a concept linked to Node.js (not AdonisJS). However, it could also go inside the |
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, 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 |
+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:
I would put Proposal
|
This is really cool 👍 1+ for me |
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. |
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
This is not the goal of the documentation and is already planned in the Bootcamp project.
|
We got an internal discussion today, here is the latest feedback and final structure we will use.
Final structure:
|
Yup, looks good. A few things to note.
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:
|
This is amazing work! Well done, much respect 🙏 |
👋🏻 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 |
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 hereThis 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.
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.
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.
This section is ordered by alphabetical order.
The goal of this section is to explain common architectural concepts we may found in other frameworks.
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.
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
orPrisma
there for example.This section is ordered in a logical way.
Another proposal for this section would be to keep all the auth guard separated:
The goal of this section is to contain anything related to authentication.
This section is ordered in a logical way.
The goal of this section is to contain anything related to securing an application.
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
orKitaJS
in the future in this section.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.
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.No change for this section.
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.
No change for this section.
FINAL SIDEBAR
The text was updated successfully, but these errors were encountered: