The number of different guides and documentation materials grew over the years,to the point where it became harder to find information unless you knew whatyou were looking for, or relied solely on the search functionality.To address this, we have decided to reorganise the guides by categories ratherthan keeping them grouped by types (guide, tutorial, etc.). In addition, we wantedto make it easier to navigate between the guides once you have already opened aspecific page.These changes affect the newer versions of guides, while the 3.27 and earlierones stay in their previous form, at least for now.What actually changed ?Curated category groups of guidesGrouping the guides by type simply stopped working with the number of differentguides that we have now. Hence, we have decided to reorganise them into categorygroups by the topic they belong to. We have kept the already familiar icons forthe guide types so that it’s also clear what to expect from a particular document.Having a small, concise group with a clear topic helps narrow down to the guide you arelooking for. Some categories are also divided into subcategories for a more fine-grainedgrouping. But as the number of groups grows, how do you discover what categories areavailable? That is why we have also introduced a navigation menu on the left that helpsyou jump from one category to another.This is a curated set of categories, and within each category, guides are placed in aspecific order: more relevant/fundamental guides to the category go first, followed bymore specialised guides.We have decided to have a dedicated pinned section where we include the guides that mayor may not be in other categories, but which we find to be useful or often visited.We have also slightly changed the guide cards style and behaviour — now they will openin the same tab rather than a new one. You can still open them in a new tab as any otherpage — just Ctrl/cmd+click as you would any other link.Updated search behaviourAfter some discussions and considerations, we landed on preserving the category groupsin the search results representation. Our concern was whether we would lose the searchrelevance if we preserve the categories when displaying search results. We addressedthis by reordering the category groups based on your search. The more relevant guidesto your query a category contains, the closer to the top of the category list it is.We have also decided to remove the highlighted content snippets from the results screen.While our intuition, when the feature was initially delivered, was that these could helpdecide whether a particular guide contains the information you are looking for, it turnedout that we would need to show much more content to provide enough context to make thatdecision. Doing so clutters an already information-heavy page even further.We’ve preserved the other search capabilities. In particular, we kept the search suggestions,which try to find something close to what you were trying to look up but may have made atypo.And as a reminder, it is a full text search, not just a keyword search!Actual guide pageThe biggest change to a guide page is also the one easiest to miss — we haveadded a full categorised list of guides that you can pull out from the leftslide-out panel — just click on that grey bar.This allows you to navigate between the guides without going back to the allguides page. It also makes it easier to explore guides from the same categoriesthat the current guide belongs to — those are expanded by default when youpull out the panel.We have also slightly modified the table of contents, and it now shows thelist of top-level sections. When you scroll through the guide the sectionyou are currently reading will be highlighted and if it has any subsections,it will expand and a corresponding subsection title will be highlighted.This helps you see where you are currently at, especially with those longerguides.Navigation examplesWe are sure that you will find your own way around the guides and have a flowthat works best for you. But we did want to share a few practical examples ofhow we ourselves navigate through the pages.Sometimes you just need to find a configuration property key and either yourIDE does not give you a suggestion, or you do not have a Dev UI running to lookit up there — well, look no further — the list of all configuration propertiesis pinned right there at the top of the guides page:If you know exactly what you are looking for, let’s say you need to look up someHibernate ORM extension specifics, you can just click on the Data category oreven more specific on the ORM and Hibernate and pick the flavour of HibernateORM you prefer, be it a regular Jakarta Persistence, Reactive, or something morehigh level as Hibernate ORM with Panache — they all are under that category.Once on the Hibernate ORM guide page you may realise that you need to check howto configure the datasources or maybe tune the Hibernate Validator for validatingthe entities — there is no need to go back to the all guides page. Just open thelist of all categorised guides hidden on the left-side pullout panel:If you aren’t quite certain what category/guide may contain the information you need,or if maybe you are looking for something that might be in the Quarkiverse — search is your best friend in this case. Just start typing what you are looking for:As search results preserve the category groups, you can easily jump from one to anotherby clicking through the categories you see on the left.What is next ?The release of these improvements also coincided with the migration of the sitefrom Jekyll to Roq (a Quarkus-powered static site generator). We would like toaddress a few remaining migration concerns first, but we are also discussingideas as possible improvements to ease the documentation discovery, lookup, andnavigation to related content.FeedbackWe would like to hear back from you and your experience navigating the Quarkus guides.What does work for you, what would you like to see us improve ?We do value your feedback and if you spot any problems — please let us know!If you are a Quarkus user or just curious, don’t be shy and join our welcoming community:provide feedback on GitHub;craft some code and push a PR;discuss with us on Zulip and on the mailing list;ask your questions on Stack Overflow.