Single HTML currently has usability advantages over regular HTML version

[ghost]

We currently have a lot of people telling us they basically only use the Single-HTML version of our documents. Especially in terms of SEO, it's probably not a good thing that everyone wants to use those multi-MB HTMLs that take forever to load.

• [ ] Ctrl-F page search -> we need full-text search for regular HTML
• [ ] book name is visible in URL (helps investigate what went wrong if the same deeplink URL does not work for a new version of the product documentation) -> split up sets???

[fsundermeyer]

What exactly is the problem? Both formats have advantages and disadvantages which IMHO rectify to continue supporting both formats.

If single HTML is a SEO problem, we should not index it. Also not a problem, IMHO--if you search for something, you are very likely searching for something specific that is covered by a chunked HTML page.

[cjschroder]

For me single HTML is faster than clicking through chapters, much easier to browse, and easy to search. So many interfaces are like a series of tiny portholes-- I don't want to click a zillion times, I want to get on with my reading.

[taroth21]

The second point Stefan mentioned above (book name visible in single-HTML) is an important point for me (for readers as well as for ourselves as writers, because it directly tells in which book to search for the info in case the link should be broken).

[r0ckarong]

Definitely search, even with full text the results would still be in disconnected documents. I find the workflow jumping between different pages not enjoyable or effective. Most of the time I need to go back to the TOC and find a different part where the information could be, this is a one button press (Home key) in Single HTML but a multi click/ multi page load in the other format.

Further, lots of times I need to read more context before or after the section that I was actually on, this is much easier to keep in my brain by just scrolling up or down (or jumping in the single document) other than switching between pages until I've finally found the thing I need. Think of it like this: You are looking for something in a book. Instead of browsing the pages back and forth, each time you need to put the book back on the shelf and pick up a fresh copy of the book and pick your next potential candidate for result from the index. That's how it feels using the multi page HTML.

Also I like being able to "collect" IDs for linking in the single html since the URL doesn't change.

[markgharvey]

Searching the single page via Ctrl-F is a big plus in saving time.
Maybe there is a better way?
Particularly when using the html doc format as demonstrated here:
https://documentation.suse.com/external-tree/en-us/suma/4.0/suse-manager/index.html

[r0ckarong]

Searching the single page via Ctrl-F is a big plus in saving time. Maybe there is a better way? Particularly when using the html doc format as demonstrated here: https://documentation.suse.com/external-tree/en-us/suma/4.0/suse-manager/index.html

SUMA is built on https://antora.org/ and completely separate from DAPS. It also (as of the last time I checked) couldn't do PDF directly. All the work in unifying the looks through DAPS stylesheets would be wasted because you would start over with designing the CSS for the website and the PDF on separate foundations. It's certainly a nice solution but it doesn't cover a lot of the output formats we need (or can't get rid of).

I researched this for CaaSP but it was just too big of a disconnect because it involves a completely different pipeline and management of the antora platform itself. I decided against it at the time because that fractures the work between projects and the "Doc Team way" even further. AsciiDoc is already a big paradigm shift and Antora on top of that just puts that ^2

SUMA uses lunr.js for search now (from what I can tell), if this could be integrated into the HTML pages for DAPS in some way then that would be a quick win.

[vmoutoussamy]

Single HTML has the advantage to fit with the "endless scroll" trend over the internet. Users on mobile device are more than happy to just scroll indefinitely rather than clicking somewhere to just continue reading. IMHO I don't see any advantage of the regular HTML version, and would ask the question the other way around, why are we keeping the regular HTML version?

[fsundermeyer]

• The regular HTML version loads much faster--the SLE Admin Guide, for example is rather huge and takes long to load. If you are on a mobile connection you would want to avoid loading the complete guide.
• IMHO most readers are not reading an entire guide or are searching for various topics in one go. They rather have specific problems they would like to get solved. reading a Chapter on a single page is sufficient for this. This is especially true for users that got to the guide via a search engine
• In case you would like to provide a link to a specific topic to a customer, it would be weird if you force them to load an entire guide if a single chapter would do.

Again, I do not understand what this discussion is about at all. Generating both, chunked and single HTML comes at no cost at all and maintaining stylesheets for both versions is a manageable effort.

[vmoutoussamy]

* The regular HTML version loads much faster--the SLE Admin Guide, for example is rather huge and takes long to load. If you are on a mobile connection you would want to avoid loading the complete guide.

But I guess there is technical solution out there to not load the entire doc at once?! but load while browsing?

* IMHO most readers are not reading an entire guide or are searching for various topics in one go. They rather have specific problems they would like to get solved. reading a Chapter on a single page is sufficient for this. This is especially true for users that got to the guide via a search engine

Yes! but IMHO using the "table of content" and "ctrl+f" are the tool of choice for the Single HTML version.

* In case you would like to provide a link to a specific topic to a customer, it would be weird if you force them to load an entire guide if a single chapter would do.

Yes, but see point above.

Again, I do not understand what this discussion is about at all. Generating both, chunked and single HTML comes at no cost at all and maintaining stylesheets for both versions is a manageable effort.

Interestingly enough:

• I guess this is only for discussion and maybe turn some suggestions as potential enhancement?
• We only provide single HTML version (no HTML, EPUB, PDF) of our Release Notes: https://www.suse.com/releasenotes/
• This is only available in Single HTML: https://documentation.suse.com/suse-distribution-migration-system/1.0/single-html/distribution-migration-system/
• I'm wondering if you have some stats about which version is the most viewed by our users. It would be cool to have some "data driven" thoughts on this topic.

[ghost]

I guess this is only for discussion and maybe turn some suggestions as potential enhancement?

Yes, realistic enhancement proposals are good.

In that sense, I am not 100% sure if we have the tools to realize e.g. your infinite-scroll suggestion, even though I like it.

We only provide single HTML version (no HTML, EPUB, PDF) of our Release Notes: https://www.suse.com/releasenotes/

True. Given the length of the SLES notes I am not always sure that is ideal. For all other products, this works however, imo.

This is only available in Single HTML: https://documentation.suse.com/suse-distribution-migration-system/1.0/single-html/distribution-migration-system/

Right, because that is a very short document.

(Sorry folks, if I forgot a bit about responding here. But your input is absolutely valued.)