Provide aggregated documentation for offline use

[esuomi]

Hi,

Seems that with Spring Boot 3.3.0 you have removed the single page variant of the reference documentation, as it now redirects to https://docs.spring.io/spring-boot/index.html. Please restore it, it's necessary for

1. fast cross referencing across the entire framework and
2. finding things which one can't remember exact names/keywords for

The segmented reference at https://docs.spring.io/spring-boot/index.html is useful only if one already knows the general structure of the whole documentation, which really doesn't apply to a casual reader since Boot is a massive project.

[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.

[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 https://github.com/spring-projects/spring-boot/issues/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.

[petenattress]

I just want to say I completely agree with all @esuomi's points. The single page HTML version of the documentation was incredibly useful to me when I was learning Spring/Spring Boot as it wasn't always obvious which section would contain the information I needed so searching with Ctrl+F and quickly scanning through became invaluable. This is especially true where the boundaries between Spring Framework, Spring Boot, Spring Data etc are a bit fuzzy - I would just have three tabs open with the three full pages and search through each to find the info I needed.

For those who are already familiar with the structure of the Spring projects and documentation I think the new Antora version is fine, but if I was coming freshly into Spring I honestly think I would struggle to use it as efficiently as I was able to use the single HTML pages. The Antora search function seems quite limited to me and there doesn't seem to be much rhyme or reason behind the order it displays results in.

The Spring documentation is generally very high quality, which is obviously important for a project of this size and complexity. It would be great to see a restoration of the single page HTML/PDF version of the docs so the usability of this valuable resource isn't impaired.

[jeanjerome]

Not to mention that a single documentation page can easily feed an LLM using RAG, which can be an advantage in current times, especially when aiming to dive into new technologies like Spring AI 😬

[GithubUser8080]

Agreed, single page was the only viable documentation for me, the current system does not work without internet, is not transferrable and you cannot use CTRL + F to easily search

[kllmanu]

Another big advantage of the single html file was the ability to create yourself an epub file out of it. One could have used pandoc to do so and read the documentation on an ebook reader.