Reorganizing our documentation

[gsmet]

Reorganizing our documentation

Note

This was supposed to be my secret project for next week, but since Rolfe is working on this in parallel, it’s probably better to put all the ideas on the table now.

Important

I don’t want perfect to be the enemy of good. We absolutely need a plan, but we also need incremental improvements. This is a problem now, and we shouldn’t wait for a grand redesign before making things better.

Also, we don't need to agree on everything to make progress and do better.

Let's start by acknowledging two things:

• We have amazing documentation content.
• We have organized it in the worst possible way :)

TL;DR (but please, read!)

• Categorize the guides to reflect our strategy and messaging.
• Improve navigation, both on index pages and within individual guides.
• Provide clear learning paths.
• Separate the documentation from the main website.

Categorization and index page

Principles

I think we all agree that the current "big bag of guides" on the index page doesn’t work.
Categorizing guides purely by type doesn’t make much sense, especially since we haven’t made significant progress on the Diataxis split.
But even if we had, users are far more likely to look for all information about a specific topic than to browse tutorials, how-tos, and reference material separately.

From what I’ve seen of Rolfe’s work, he independently arrived at the same conclusion.

Interestingly, we used to have a manually curated index page.
I think we need to go back to that, but this time it must live in the main repository, with tooling that fails the build if a newly added guide isn’t properly categorized and included in the index.

We also need a stronger categorization model. Some areas, Security, for instance, clearly require subcategories.

So once we move from a “big bag of guides” to a carefully curated and categorized list, what do we do with it?

The index page should present these organized guides in a way that is digestible.
That means a much more compact layout.
From what I could see of Rolfe’s prototype, he reached the same conclusion.
I’m not sure I would go as far as showing only guide titles, they are not always self-explanatory, but we do need a layout that allows users to scan quickly.

We should also:

• Include a prominent link to the full list of configuration properties at the top.
• Provide anchor links to quickly navigate to specific categories and subcategories.

OK, now we have a well-organized index page.

Let’s click on a guide.

Categorizing

Categorizing the guides is easier said than done. But we should follow one essential principle:
categorization must reflect our marketing strategy and messaging.

For instance:

• Native guides should not live under “Getting Started”. They belong in a “Going Native” section, with a short introductory paragraph explaining why and when going native makes sense.
• Reactive guides should not live under “Getting Started” either. They deserve a “Going Full Reactive” section, again with a concise explanation of the value proposition and the typical use cases.

This is extremely important.
Categorization is not just about organization; it directly shapes how people understand Quarkus and the paths they believe are available to them.

We need to be deliberate and consistent in how we structure it.

Guide page

Once you click on a guide, you need context.

You should also be able to move quickly to another guide, whether it’s:

• A guide about the same extension (the data already exists).
• A guide about a related topic (the data already exists).
• A completely unrelated guide.

So I think we should:

• Provide a categorized navigation menu on the left, exposing the full documentation structure. Rolfe went in this direction as well. I’m not convinced it should always be visible, perhaps a toggle button could reveal it as a slide-in overlay. When opened, it must be contextualized to the current guide.
• Display topic labels below the guide title. Clicking a label would show the list of guides for that topic (we already have the logic to support this).
• Display extension labels in the same way, with identical behavior.

Once we do this, the guide is no longer an isolated page, it is clearly positioned within the broader documentation structure.

Then there is the Diataxis classification (Concepts / Tutorial / Reference), which already applies to some guides. When applicable, we must ensure the three are explicitly cross-linked.
My proposal would be to display a Concepts | Tutorial | Reference navigation element above the table of contents whenever the classification exists.

Learning paths

This is an idea I’ve had several times, but I’ve never really formalized it.

We have different types of users:

1. Those who want to discover what Quarkus is capable of.
2. Those who know exactly what they’re looking for.
3. Those coming from other ecosystems who understand the concepts, but don’t yet know how they translate to Quarkus.
4. True beginners who don’t yet know how to build a Java application (we all started there!).

I think we serve 1/, 2/, and 4/ reasonably well, though we could still improve for 4/.

But for 3/, we are not addressing the problem at all.

Quarkus offers many options. Without guidance, it’s extremely difficult to determine which one is appropriate just by reading individual guides.

This is where learning paths come in.

We should define curated learning paths — carefully selected sequences of guides that address a specific goal or requirement.

For example:

• How do I build a RESTful CRUD application with Quarkus?
  • REST
  • Data access / CRUD
  • Authentication
  • Authorization
• How do I build a messaging-driven application with Quarkus?
• How should I package my Quarkus application? What are the trade-offs between the available options, and when should I use each?

This is still very rough, but the idea is simple.
We need to guide users toward recommended approaches and best practices.
We cannot just hand people a large collection of guides and expect them to assemble the right architecture on their own.

That doesn’t mean we hide alternatives, but we must clearly explain when and why each option should be used.

Splitting the websites

I think we should seriously consider separating the documentation from the main website.

This would allow us to keep a very lean top-level navigation and dedicate the full layout to documentation concerns.
Documentation and marketing serve different purposes.
Trying to optimize a single website for both inevitably leads to compromises.
With a dedicated documentation site, we could design a layout entirely focused on learning, navigation, and discoverability.

There are also practical benefits:
documentation and marketing content have very different lifecycles, so you wouldn’t need to rebuild the entire website just to check the documentation, and vice versa.

[gsmet]

/cc @rolfedh I tried to dump all the ideas I had here, let me know what you think. I already started working on the categorization. As mentioned in what I wrote, I think we independently arrived to very similar conclusions. And that we could make relatively fast iterations. I'll have a closer look to what you did next week.

/cc @alinnert this is what I had in mind when I told you in quarkusio/quarkusio.github.io#418 that it was on our radar. Let me know what you think.

[sberyozkin]

I also like the idea of the idea of the hierarchical views, #20625, and guiding the user to a specific piece of the documentation they actually need, #21075.

The former might be duplicating some of your ideas, the latter is worth investigating further IMHO.

[gsmet]

I think #20625 is in line with the notion of categories/subcategories. But we might need to go further. The idea is to do a first categorization, see what works what doesn't, and then refine further if needed. Security is definitely an area that will require special attention.

As for #21075, it certainly makes sense. But it's something we could add later. As you basically need a small app to guide you to the right content.

[maxandersen]

100% agree.

I can tell you after not looking at the docs daily I'm totally lost when trying to find content.

One thing I still find hard to locate is the all config - it because I want a all config page (since it's not really all) is just its the only page I can search and find configuration reliably.

And 1000% of separating main website and docs. Not just for being able to archive (not as in removing but in not having to keep updating/regenerating) but also for thinking through how quarkiverse and camel extensions fits into this without everything being published all at the same time.

P.s. is rolfs prototype viewable somewhere ?

[rolfedh]

Thanks for asking, @maxandersen. I'll post a link here later today after I complete some updates and refresh some screenshots.

[cescoffier]

Hello,

Great initiative! It's definitely time to move past the 'big bag of guides' approach. A few thoughts on the proposal:

• I noticed the 'How-to' category (from Diátaxis) seems to have been dropped or merged. In the original framework, how-tos are the bread and butter for developers who already know what they want to achieve but need the steps to get there. Not everything fits into a tutorial or a reference. Any reason for moving away from that specific distinction?

• I’d suggest being more granular on the Getting Started. I totally agree with the strategy on native and reactive, but if 'Getting Started' is restricted to a basic CRUD app, we might be underselling the platform. We could offer 'Getting Started' paths for different personas: CRUD/Web, CLI, Messaging/EDA, and AI. This would immediately showcase how versatile Quarkus is.

• Maintaining manual links between guides is a nightmare. Have we considered using LLMs/AI to help curate or suggest these links? I’ve experimented with this for my personal knowledge base, and the results were surprisingly solid.

Looking forward to seeing this evolve!

[gsmet]

Maintaining manual links between guides is a nightmare. Have we considered using LLMs/AI to help curate or suggest these links

We already have something for that based on minimal metadata about topics and extensions based on each guide. We just need to make it more visible IMO.

Not saying at some point LLM can’t be used. But we have the data to do it already without it as a first step.

(See the related content section at the end of the guides)

[brunobat]

Interesting @gsmet. I think I did something similar to what you describe with the Observability reference guide: https://quarkus.io/guides/observability
Also when you open a sub-page they all have a reference to the main guide.

I also think we should have a last updated dated on each page... Sometimes we have pages with similar content but doing it in different ways and it's hard to know which one is the most recent recommendation.

I'm not sure about splitting the docs domain. The advantage you mentioned seems to be less interesting when we will break the SEO and have duplicated links for the same thing on google search. I would leave it like it is now, the domain.

[gsmet]

You don’t necessarily break the SEO. We have CloudFlare in front so we can rewrite URLs properly now.

That being said, we could have a different layout on the same domain and keeping the URLs as is if that’s what we want.

I just don’t think it’s a good idea to have our marketing material decide how our doc looks.

That being said, it’s definitely not the priority. I think we should focus on the rest first.

[holly-cummins]

This is much-needed, yay!

I think we should seriously consider separating the documentation from the main website.
documentation and marketing content have very different lifecycles, so you wouldn’t need to rebuild the entire website just to check the documentation, and vice versa.

I can see I might change my mind, but I’m not at all sure about splitting out docs from the main landing page. Whenever I see other sites doing that, it feels fragmented, and I just assume they just prioritised their internal developer convenience over the external user experience. :) 


Jokes aside, I suspect what usually happens is that they had two teams doing the two things, and the two teams didn’t talk to each other - Conway’s law for information architecture.) Since we’ve already fixed the fragmentation problem and figured out how to talk to each other, I’d be sad to see us un-fix it.

That doesn’t mean they have to live in the same repo (and they kind of already don’t), or be built on the same technology, but the external navigation should be unified, IMO. We can have a nice top-level landing page for docs that we can share, but I think it's nicest if there is a common top-level navigation experience in both. We can supplement that with a richer docs-specific navigation experience in the docs sub-site. This is what we do for the extensions pages, for example.

I also think that although the two audiences are in general are pretty different, there is some overlap in content needs, for example, getting started guides. It would be weird not to include them in the docs site, but they'd also be the first next step for people looking at the marketing site.

[gsmet]

I don’t think I presented the split as a convenience for us.

I don’t think the layout of the website is appropriate for the doc.

Now if we can make sure the doc has an appropriate while still on the website then fine. But atm I’m not very satisfied with the doc layout.

[gsmet]

Also I visited doc sites from some other projects and they are often split and with a specific layout that works better.

[rolfedh]

@maxandersen Here's the prototype PR — it's essentially a Jekyll site template. Please treat all categories and nav text as placeholder content illustrating the concept rather than final proposals. Both would need revision and refinement before anything goes forward.

[rolfedh]

I've opened #52780 as a first step toward making navigation fully author-driven.

The PR adds the mechanism described in its own docs/design/author-driven-navigation.md file:

• :categories: and :subcategories: drive placement. A central config file (navigation-config.yaml) defines valid categories, subcategories, display titles, and display order. The build validates every guide's attributes against it.
• :nav-title: provides sidebar labels. Optional. when omitted, the document title is used automatically. Required only when the title exceeds 40 characters.
• A placement rule handles subcategory grouping. Guides land under subcategory headings when the subcategory belongs to their category, or appear in both places when it doesn't.
• Learning paths support curated, ordered guide sequences (as you proposed).
• Strict/lenient validation. Strict by default (CI fails on issues); -Dvalidation=lenient converts to warnings for local iteration.

The config file is seeded from the existing Category enum, so all current :categories: values are valid from day one. Migration is incremental, one guide or one category at a time.

A follow-up PR will illustrate the mechanism by restructuring a crowded category (e.g., security) with subcategories and updated nav-titles.

Feedback welcome, especially on the open questions in the design doc (category inventory, template key renames).

[holly-cummins]

:categories: and :subcategories: drive placement.** A central config file (navigation-config.yaml) defines valid categories, subcategories, display titles, and display order. The build validates every guide's attributes against it.

Further to the (long!) discussion over on https://quarkusio.zulipchat.com/#narrow/channel/187038-dev/topic/Categories/near/575853110, I wonder if we should think about the use of "category" here. We use "category" in this context to mean "topic", and we use it elsewhere in our UI (like code.quarkus.io, and extensions.quarkus.io), for a specific extension taxonomy. There's some overlap between the two ("Business Automation" features in both, for example), but some divergence ("Writing extensions," or "Tooling" is only in the guide-categories, not in the extension-categories). I wonder if using "topic" might make it more clear that the two lists aren't intended to be the same? Or, alternatively, if the two are intended to be the same, we might want to make that explicit and link the two category inventories.

[rolfedh]

@holly-cummins I'll be happy to adjust the terminology to improve clarity. For now though, let's wait: @gsmet has suggested holding off while he prepares to suggest a different approach.

If you're interested, I finalized a prototype that addresses some of the more significant suggestions in this thread:

• quarkusio/quarkus#52780 — Generates navigation.yaml from adoc attributes during the docs build and delivers it via sync-web-site.sh. (Also see the design document and contributor guides for documentation).
• quarkusio/quarkusio.github.io#2555 — Adds domain-based navigation templates (sidebar, landing page, prev/next) that consume navigation.yaml.

I've also attached a pair of PDFs that show the results. What I like about this prototype is that we would be able to start using it with our current guides and progressively sort them into categories:

• Guides - Latest - Quarkus.pdf
• Building a Native Executable - Quarkus.pdf