Provide aggregated documentation for offline use about spring-boot

[wilkinsona]

reduced network bandwidth usage

I think this is an area where the new documentation excels. https://docs.spring.io/spring-boot/docs/3.2.x/reference/htmlsingle/index.html weighs in at 470KB where as each individual page of the new docs has HTML in the 10KB - 20KB range. This also shows in the rendering time with the single page docs taking almost 8 seconds according to the timeline in Safari vs 3 seconds for a page of the Antora-based docs.

We don't consider the current docs to be finished, documentation almost never is, and that's especially true here as this is the first iteration of them with the new Antora-based structure. As such, I expect things to evolve based on feedback such as this. For example, the point about cross-references in a good one and I suspect that we'll want to add many more now that the pages are more fine-grained. We should make sure that we keep this in mind when tackling #40064.

One thing that I think I can say with some certainty is that we won't be going back to the old documentation structure instead of the Antora-based docs. Assuming that Antora supports it, what we can consider is also publishing single-page documentation either as HTML or perhaps as a PDF. Right now, though, my preference would be to continue to evolve and improve the documentation in its new format as there are some significant advantages to not publishing the same content in multiple formats, not least search engine discoverability which has hampered our docs for years.

[philwebb]

There is an effort underway in the Antora community to address the "single page documentation" requirement. I think it's mostly focused on PDF generation at the moment.

I would very much like to be able to publish some aggregated form of our documentation. I think a lot of folks would like to be able to download something that they can read offline.

I'll repurpose this issue to look into that, but it's something we'll likely want to tackle as broader team to that all projects can benefit. As such, I suspect it may take a little time.

I wish we had a simple switch we could throw that would allow us to restore the single page HTML generator. Unfortunately, it's not that easy and we don't have the bandwidth to maintain two distinct sets of .adoc files.

[wilkinsona]

Thanks for the feedback.

fast cross referencing across the entire framework

Spring Boot 3.3 has moved to Antora for its documentation, aligning with various other projects that have already moved over the past several months. One of the main benefits of Antora is that you can now search across the entire Spring portfolio from Spring Boot's documentation. You can access this search at https://docs.spring.io/spring-boot/search.html or by clicking in the search box on the left-hand side and then selecting Search in all Spring docs.

finding things which one can't remember exact names/keywords for

Can you please describe how would you do this with the single-page documentation?

[esuomi]

Spring Boot 3.3 has moved to Antora for its documentation, aligning with various other projects that have already moved over the past several months.

To be blunt, in all honesty I don't like this move at all :) It's all too granular.

Can you please describe how would you do this with the single-page documentation?

As a recent example, lets say I'm interested in learning more about how to do custom health checks for actuator.

1. From googling, I learned that the relevant class is HealthIndicator. I also learned about liveness and readiness.
2. In the documentation I would use a mix of terms - name of the relevant class, related keywords such as "custom health", and some side keywords such as "readiness" and "liveness" to understand where in the document all of these are referenced and how they relate to each other.

To be clear, it's not just about finding the correct snippets and sections of the documentation, but also about seeing their relative proximity and order as well. No documentation is perfect, and it's very easy to forget to do cross-references, so Ctrl/Cmd+F:ing the full document gets around that nicely, without losing the spot at where I was in general in the documentation. If my various keywords all point to hotspots at around, say 2/5ths mark of the page and towards the last quarter, it means the relevant related sections for understanding how everything meshes together are around those parts. For me this exploration and overview is quite important for any documentation.

And while I don't personally rank these that high, there are some other secondary benefits to single-page docs as well, including printing, reader mode support, reduced network bandwidth usage, and whatever else others may enjoy.