Update header navigation with new 'Why Quarkus' tab

[chrischiedo]

Short summary:
This PR updates the header navigation with a new "Why Quarkus" menu tab that contains five of the six items that were previously under the "About" tab.

Changes made:

• Add a new "Why Quarkus" dropdown menu tab with links to the main reasons for choosing/using Quarkus (container-first, reactive, developer joy, kubernetes, standards).
  
  Motivation:
  I think that having the strengths/advantages of Quarkus listed under the About tab seems a bit odd (and less conspicuous). I think having them under the "Why Quarkus" tab clearly speaks to the reasons WHY one would/should choose Quarkus.
• Add a new item under the "About" dropdown tab that describes the Quarkus ecosystem of community projects (I'd appreciate feedback on the description of some of the projects - I'm not an expert in Quarkus...yet).
  
  Motivation:
  Instead of having only a single item under the "About" menu tab (having moved the rest to the "Why Quarkus" section), I think adding a section giving brief descriptions of some of the community projects that Quarkus leverages makes sense (and aligns with the theme of sharing something extra "about" the Quarkus framework).
• Rename "Documentation" to "Guides" under the "Learn" menu tab.
  
  Motivation:
  While "guides" can technically be considered as a subset/type of documentation, I think documentation "proper" has a more broader sense. The existing content has a mix of tutorials, how-to guides, conceptual docs, and references. My point of view is that only the first two categories fit well under "guides", and perhaps we need to introduce another section for documentation (maybe quarkus.io/docs?). That would then host the conceptual docs, references, and a "user guide" (that covers things like: Dependency Injection in Quarkus, Testing in Quarkus, Data Access/ ORM in Quarkus, Security in Quarkus,etc.). We could even have Quarkus API documentation in there too. I'd be curious to know what other folks think about this suggestion/proposed change.

cc: @gsmet

[holly-cummins]

I like the idea of a "Why Quarkus" section. The ecosystem should probably cross-link to "Browse Extensions" and also "Share extensions."

Maybe a paragraph at the bottom, something like

If you'd like to see the full list of extensions, you can browse it on http://quarkus.io/extensions. And if you'd like to join the ecosystem yourself, here's how..

[gsmet]

@insectengine I think your feedback would be interesting here. Thanks!

[github-actions]

🎊 PR Preview 1df911d has been successfully built and deployed to https://quarkus-website-pr-1763-preview.surge.sh

[insectengine]

@gsmet - thanks for bringing this to my attention.

@chrischiedo - Thank you for putting the effort into this.

Reorganizing the primary navigation:
Look at the proposed change, it seems more like a questioning of the naming of the primary nav element "about" verses separating out to another section. All of the content in the current about section describe both what Quarkus is and what its advantages are. I don't see an advantage for splitting this content into two sections. Does the name "About" not service the content and help the user? Then what name would? Additionally, we have plans for new content pages to add to this section.

Ecosystem page:
It seems the creation of this page seems to be a response to the problem of only having a singular "What is Quarkus" under a stripped down "About" section. "Ecosystem" is a very loaded (and precious) name so we need to be very careful about how and where we use it. The page as it currently sits is a great explanation of what makes up the Quarkus project. I'd suggest this page content should be added to the "What is Quarkus" page.

Documentation vs Guides
I disagree with the suggestion to change the name of the section back to "Guides" (and split content). We're in the middle of a wholesale change of how we create and organize our documentation. Originally, we just had guides but now we're moving to the diataxis framework with tutorials, how-to guides, conceptual docs, and reference docs (as Chris pointed out). We purposely choose to change the name of the section from "Guides" to "Documentation" to properly characterize the broadness of the content. Having a singular Documentation section gives the user a singular place to view all of the various types of documentation verses have them skip around various sections of the site to access it.

[chrischiedo]

@insectengine - Thank you for your feedback!

Reorganizing the primary navigation:
My primary motivation here was to be explicit about why one would choose Quarkus (presumably over other competitors in the same space). My concern isn't really about the naming: having the "About" section is great, but I do think that having "advantages/reasons to use Quarkus" under it makes those reasons stand out less. Also, as it is laid out currently, it is a bit tricky to decide whether the items listed under the "About" section (after "What is Quarkus") are features of Quarkus, OR advantages, OR both. My humble opinion is that sometimes features != advantages, and therefore it helps to be explicit ("Don't let the user think too much about your intentions" is one of the lessons I picked from Content Design, a great book by Sarah Winters).

Ecosystem page:
I agree with you here. "Ecosystem" might be a heavy term in this case. I am okay with moving the current content of the ecosystem page to the "What is Quarkus" page (or perhaps keeping the page, but renaming it to something less loaded?)
I'd be curious to hear what @holly-cummins thinks about this (keeping in mind her previous comment). While commenting on the primary navigation, you mentioned that you have plans for new content pages to be added under the "About" section. I think with the addition of the new content, the issue of having only a single item under the "About" section would be solved.

Documentation vs Guides:
Thanks for the background context! I didn't know that the node was initially named "Guides". My main motivation here was to call out the fact that "guides" are a subset of documentation and that with a title of "Documentation", a user would expect a lot more than just "task-oriented guides". But I totally agree with your feedback here. My only suggestion would be for us to be consistent with the naming: while the title of the item is "Documentation", the link leads to quarkus.io/guides. Seems like a nit, but I think one would naturally expect the link to be quarkus.io/docs (or something close to that).

Sidenote: I think the Micronaut folks have done a great job of separating the two aspects of "Documentation" vs "Guides".

Note: I'll wait for your responses/feedback and then make the necessary changes to this PR.

cc: @gsmet

[holly-cummins]

Thanks for the thoughtful response, @chrischiedo.

Ecosystem page: I agree with you here. "Ecosystem" might be a heavy term in this case. I am okay with moving the current content of the ecosystem page to the "What is Quarkus" page (or perhaps keeping the page, but renaming it to something less loaded?) I'd be curious to hear what @holly-cummins thinks about this (keeping in mind her previous comment). While commenting on the primary navigation, you mentioned that you have plans for new content pages to be added under the "About" section. I think with the addition of the new content, the issue of having only a single item under the "About" section would be solved.

I think renaming the Ecosystem page to something less overloaded than 'Ecosystem' is a good start, but I'm still a bit concerned by the overlaps between it and our other ecosystem content. I think we should try and have a very good idea in our head of what problem we're trying to solve with this page. Is the aim to show users a hand-curated selection of integrations? This is definitely a useful aim - but I wonder whether quarkus.io/extensions isn't a better place for that. (We've had it on our todo list for ages to do some hand-curation and a 'featured' top bar, as well as a more automatic default sort by popularity.) The granularity of the items on ecosystem.html is bigger than a single extension in most cases, but maybe the default granularity on extensions.quarkus.io should also be larger than a single extension? (@gastaldi asked for this a while ago).

As well as extensions, the ecosystem.page has some things that definitely shouldn't be on extensions.quarkus.io, like programming models and 'libraries we bake into the Quarkus platform'. So I guess that comes back to 'what problem are we trying to solve?' ... are we trying to give developers an idea of what kind of programming models they'll be using? or trying to reassure people that we're built on top of tried and tested libraries? or trying to give back thanks to the communities whose work we consume?

[insectengine]

Reorganizing the primary navigation:
I get what you're saying about trying to be explicit with the Why of Quarkus and using a title like "About" seems to miss the mark. From my perspective, I don't see the need to create a new primary tab element to split off the "why" and only have one element for "about". It seems like the real discussion would be, what is the appropriate name for that section of content. The "What is Quarkus" content would still make sense to be in that section.

Here is a tracking board were we're outlining some future content pages:
https://github.com/orgs/quarkusio/projects/19

There are several proposed landing pages that would fit into the Why section as well.

Ecosystem page:
With renaming the About section, the need to create a page of content just to fill in the section goes away. This content is more about what makes up Quarkus so I think it makes more sense to use it to revamp the "What is Quarkus" page.

Documentation vs Guides:
Yes, we didn't change the URL because of legacy issues. Quarkus.io/guides should be Quarkus.io/documentation. The plan is to continue to build out new content and revise old content to fit the Diataxis framework. The current docs page is a blended/hybrid approach until we have enough content migrated. I agree with you, in the meantime we should look to make a cut over from /guides to /docs or /documentation.

On @holly-cummins points, yes we need to do a better job of explaining to our users about the Quarkus ecosystem and how extensions play and important role.

[chrischiedo]

As well as extensions, the ecosystem.page has some things that definitely shouldn't be on extensions.quarkus.io, like programming models and 'libraries we bake into the Quarkus platform'. So I guess that comes back to 'what problem are we trying to solve?' ... are we trying to give developers an idea of what kind of programming models they'll be using? or trying to reassure people that we're built on top of tried and tested libraries? or trying to give back thanks to the communities whose work we consume?

My initial reasoning around the use of the term "Ecosystem" was to convey the idea that Quarkus heavily builds upon existing, mature libraries/frameworks from the Java enterprise ecosystem. That learning/using Quarkus won't need you to learn a bunch of completely new stuff in order to be productive, but rather you'll leverage your existing knowledge from the Java enterprise space. And I think that matches with what you are describing as "...(existing?) programming models and libraries we bake into the Quarkus platform".

Therefore if I were to rephrase this in terms of a "problem we are trying to solve", then I would go with:
"...trying to reassure people that Quarkus is built on top of tried and tested libraries", and that we are not trying to reinvent the wheel (especially when it comes to some of the basic/fundamental building blocks of the framework).

But based on the previous feedback from @insectengine, I can easily see why using the term "ecosystem" in this sense would be a bit restrictive. And as you've already alluded to, extensions would technically be considered as part of the ecosystem too.

cc: @holly-cummins

[insectengine]

@chrischiedo - Thanks for bring up this topic. It's caused some good conversations about the prime navigation and some holes in our content. I'm going to work with @holly-cummins and put in a PR to change the name of the About prime navigation section to Why. I'm also going to put in a draft PR to cover adding your content from the proposed Ecosystem page to the What is Quarkus page. There needs to be some more conversation around the exact wording.

Thank you so much for putting the effort into this!

[maxandersen]

@chrischiedo thanks for the idea on putting "Why" on front page - just realized I hit merge without checking you were marked as coauthor. was not my intent.

@insectengine if there is a PR with content from @chrischiedo let me know and I'll show how we can add him as co-contributor to that PR.

[chrischiedo]

was not my intent

@maxandersen - No problem at all. I'm really excited about the Quarkus project and I'm glad to contribute in any little way that I can.