Closed mojavelinux closed 1 month ago
mojavelinux
commented
4 months ago there is the right navigation sub-TOC (does it have a more precise name? Page TOC?).
The sidebar on the right is the page TOC (or page contents for short). The sidebar on the left is the site navigation, not a TOC.
mojavelinux
commented
4 months ago I have updated the migration script to combine the pages for the chapters (the top-level navigation entries) as requested. That includes the following chapters in the operations guide:
I partially consolidated the Jetty Modules by only keeping Custom Jetty Modules and Standard Modules as separate pages.
Jetty Start Mechanism I would coalesce children pages, except Starting Jetty using JPMS. The idea is to provide a single page for the normal start mechanism, and a more specific page for JPMS because it's a more rare configuration.
I extracted a page for Starting Jetty using JPMS and combined the rest of the pages in the Jetty Start Mechanism chapter.
Java Server Pages, JavaServer Pages Standard Tag Libraries, and JavaServer Faces TagLibs should all be in a single page, with a more generic title such as "JSP, JSTL and JSF" and 3 children sections.
The migrations script cannot combine chapters. I've made these all single pages for now. You can combine them into a single chapter after the migration is complete.
Server Libraries: I would move the I/O architecture section either first for both client and server, or last for both. Perhaps I like last better because it's for advanced users.
The migration script cannot rearrange sections. This is something you'll need to do post migration.
Maven and Jetty clicks, but nothing happens? Jetty Architecture clicks, but nothing happens? Migration Guides clicks but nothing happens?
Yes something happens. The pages are revealing the navigation. There is no index page since there was no content before the first section (which is now a separate page). One there is a page there, it will navigate to it, but that is something you'll need to add post migration since there is no content to migrate.
About the Using Maven section, I am not sure
I'm not sure what you are asking. You need to be more clear about where you want the page splits to be.
mojavelinux
commented
4 months ago I think by coalescing the subsections we will arrive at a manageable number of pages that contain a single argument and its details that should be good for both SEO and ChatGPT.
Just to be clear, combining pages is not necessary good for SEO. That's because search engines can only link to pages, not sections within a page. It's much better to have one page per searchable topic. That way, the search result will point directly to that topic.
Consider the following use case. In Asciidoctor PDF, there's a section in "Optimize the PDF" named "Rasterizing the PDF". If I search for "asciidoctor pdf rasterizing the pdf", the best the search engine can do for me is to link me to the top of the "Optimize the PDF" page. The reader now has to find the topic they searched for on that page themselves. So I've lost an opportunity there to link directly to a page on the specific topic.
Now let's say the reader wants to find information about how to import a PDF page. If I search for "asciidoctor pdf import PDF page" I get right to the page on that topic without any need to find the section information within the page.
It may be the case that you want to the search result to take the reader to the top of a page when a match is found on the page. But that's how you need to think about search results and SEO. It's not magic. There's only so much the search engine can and is willing to do. One thing is for sure is that if there is a page with a title that matches what the reader searched for (e.g., asciidoctor pdf import PDF page), they are going to be able to find exactly what they need very quickly.
jmcc0nn3ll
commented
2 months ago @sbordet can you take a peek at this issue
jmcc0nn3ll
commented
1 month ago we are live, I think this is good to close
We received the following feedback from Simone about the page splitting:
below my feedback on the current state of the documentation on Antora at https://webtide.github.io/jetty.website/docs/jetty/12/.
Operations Guide
I see you fixed the "begin" section, that's great. A single page for that is perfect, especially because there is the right navigation sub-TOC (does it have a more precise name? Page TOC?).
Jetty Features page can remain as is and possibly be expanded with information about Jakarta EE environments.
Jetty HowTos page, I can live with it as along as it is just a link to another section with the extended docs.
Architecture Overview I would coalesce the children pages like you have done for the Begin section.
Jetty Start Mechanism I would coalesce children pages, except Starting Jetty using JPMS. The idea is to provide a single page for the normal start mechanism, and a more specific page for JPMS because it's a more rare configuration.
Jetty Modules I would coalesce the children pages, except: Custom Jetty Modules and Standard Modules. Again the idea is to have the module system in one page, a lesser used mechanism (writing a custom module) in a separate page, and the standard modules (quite a long page) also separate.
I would coalesce all children pages for:
Annotations I am on the fence... On one side, feels like we are missing a more explicit Jakarta EE 10 section. Perhaps it can be folded into Web Application Deployment. I would coalesce the children pages for now, and maybe reorganize it later.
Java Server Pages, JavaServer Pages Standard Tag Libraries, and JavaServer Faces TagLibs should all be in a single page, with a more generic title such as "JSP, JSTL and JSF" and 3 children sections.
Jetty Tools is clickable, but nothing happens? Coalesce it with the child page.
Programming Guide
Client Libraries: OK, but see next.
Server Libraries: I would move the I/O architecture section either first for both client and server, or last for both. Perhaps I like last better because it's for advanced users.
Maven and Jetty clicks, but nothing happens? About the Using Maven section, I am not sure... seems like a basic how to develop with Maven that has not much to do with Jetty, so perhaps remove it? The Jetty Maven Plugin section and Jetty JSPC Maven Plugin should remain separate.
Jetty Architecture clicks, but nothing happens? The subsections are OK.
Troubleshooting Jetty I would coalesce the children pages.
Migration Guides clicks but nothing happens? The subsections are OK.