New docs is hard to read and understand

[Barbapapazes]

Package version

no

Describe the bug

would love to help you shaping documentation 💛

Hello,

First, thanks and congratulation for the v6. 🙌

But, even if the framework looks very well, the documentation is hard to read. Let me explain it.

Full width for a website could have a nice look but for a documentation, I do not think it's a good idea. Here how it looks on my computer:

I have to go from right, the TOC, to the left, the nav, it's tiring.

Then, I do not understand the nav.

The getting started section is not a getting started section. At that point, I do not really care of config or env vars or even FAQs. I'm testing the frameworks to see if it fit my needs.

Why is HTTP so huge? You say in the /guides/http that this layer is composed from router, controllers, HttpContext, Middelware, Global Exception handler and Server. There are the part I expect from this section.

Why Views and Template loose it's section? It's important for a web framework to render a view! It's now in the HTTP section but there nothing about it in the introduction of the section.

Why fundamentals come from after mail? The IoC container, the service provider and more are things that make Adonis different (and better) that any other JS frameworks. And despite that the section is called "Fundamentals", it's at the end of the nav.

Scaffolding, Tooling, Async Local Storage and TypeScript build process are important, yes, but clearly not a fundamentals for a beginner.

Extending the framework is cool but clearly advanced usage. Not needed in the fundamentals section.

Digging Deeper looks like a "everything you don't know where to put". Internationalization is important, same for authorization but it's put under a no name section.

Ace command line is at the end, after the commad-line tests? I'm testing an ace command line but I still do not know what an ace command line is.

Many parts of AdonisJS have been extracted with their own website like Japa, Edge, Vine, Lucid. That's nice but it's complicated to find them, so many click from the AdonisJS docs to the correct website. I expect a big button to easily understand that I can learn more on a dedicated website. Views page seems limited with not a lot of content but it's only because everything have move to the website of Edge.

Suggestions

• Introduction but cover more specificity of the framework (IoC, all-in-one, modular, extensible)
• Create an architecture section which explain, in-depth, how the framework works, IoC, services, extensibility, packages....)
• HTTP is not a great name (actually) because we expect a WS section or even a TCP one. Name it Concepts or Basics and put under it only the necessary to understand, globally, Adonis. Nothing specific like File uploads, validation, URL builder, views, static file server...
• Social authentication must be put under the auth section
• Authorization could be put under auth or security
• I18n could have it's own section
• Saffolding, Tooling, ... are pages for degging deeper section
• You could create a Guides section with file uploads, validation, assets bundling, logger, emitter
• Ace command line could be renamed Command Line since you do not have any other name in title (no Japa, Edge and more) and the section could come before others. REPL could be in the Basis section.
• Add a menu with all related packages (Japa, Vine, Edge)...
• Linked pages to their package using links under the toc
• Having a "edit this page" link under the toc

There is many things we could do but I think it's a great overview on how you could improve the documentation.

Reproduction repo

No response

[thetutlage]

Sorry, I did not read the full message since it appears expecting us to change almost the entire documentation without first trying to understand our intent behind writing it.

I suggest pick one topic at a time and discuss if that needs improvement. For practical reasons, I do not see myself changing the entire documentation upside down

[Barbapapazes]

Sorry, I did not read the full message since it appears expecting us to change almost the entire documentation without first trying to understand our intent behind writing it.

I suggest pick one topic at a time and discuss if that needs improvement. For practical reasons, I do not see myself changing the entire documentation upside down

Hello,

I do not want to change the entire documentation. Actual content is great!

I'm speaking about some logical changes. But anyway, I understand your point and I will take all of them, one by one, to try to improve documentation.

[thetutlage]

I'm speaking about some logical changes. But anyway, I understand your point and I will take all of them, one by one, to try to improve documentation.

Yup, incremental changes will be easier for everyone including me. It's hard for me to take such a huge feedback and take any action with it.

---

Also, one more thing which might be clear from our communication. AdonisJS documentation is a reference guide and does not aim to serve as a tutorial.

What is a reference guide (as per our understanding)?

A reference guide is something you can reference as you try to build something with AdonisJS. You use it to get technical knowledge about a particular topic.

• Reference guides are not sequential in navigation.
• They do not teach how to build something end to end.

---

We need a tutorial and that will be its own thing.