Choose domain name strategy

[jmcc0nn3ll]

@mojavelinux and @graphitefriction, now that you both are in deep and have digested how things are set up, do you have any course corrections or recommendations we should decide on early?

I am curious about the subdomain separation you have on asciidoctor, and now that we have full control of jetty.org, I want to make sure we get things right, as we should be hesitant to change structural things down the road.

We could always have a quick meeting to talk about it if necessary.

[mojavelinux]

I've renamed this issue to keep it focused on a single topic. "Suggestions?" is entirely too broad and not actionable.

Here's the original comment I captured from a comment on a different issue:

Which is better?

• jetty.org/documentation
• docs.jetty.org

I am leaning toward the second one since it looks cleaner. Regardless, the documentation landing page should show the component sidebar.

This may mean we have javadoc.jetty.org with a landing page of javadoc links.

[jmcc0nn3ll]

i realized jetty.org/docs would be better for the first option, but the question stands which will be better

[mojavelinux]

The problem with the second option is that it means having two different sites (an Antora site, or any site generator, can only target a single domain). Splitting it up that way was not in the original plan. That's not to say it isn't attainable, but it is a course change.

There are times when we advocate for the use of the docs subdomain for docs. That's typically when the main site is controlled by a different entity and it becomes really confusing and contentious to maintain content in a subfolder. But I see this more as an integrated site, in which case the documentation fits neatly as a subfolder. Or you can think of it the other way, which is that the documentation has some accompanying landing pages.

To be clear, there would be no docs folder. Rather, the folder would be named jetty because that's the name of the component in Antora. Antora doesn't currently support adding another level of folder nesting (like docs/jetty) out of the box, though it could be tailored using an Antora extension.

If you wanted a docs home page, then it would be another component named "docs" that just has a landing page. But that just seems like another page the user has to click through to get to the actual docs. Better would be a page in the ROOT component named docs.adoc that provides that entry point.

You could still redirect docs.jetty.org for people looking for it. Once they are on the pages, they rarely pay attention to the URL.

[jmcc0nn3ll]

Well that makes sense.

We've had that documentation landing page for a long time, and I feel like we need some sort of explanation of what the operations guide is versus the developer guide.

I think I misused the term, doc.adoc is kind of what I was referring to as the landing page, somewhat analogous to our current documentation/index.html

I mentioned the subdomain because I saw that's what you were doing on asciidoctor.org

[mojavelinux]

I mentioned the subdomain because I saw that's what you were doing on asciidoctor.org

Yep, that's because we already had an existing site at asciidoctor.org and we could not migrate everything over at the time. Antora also didn't have a ROOT component then, so there was no way to put files at the top-level. Now there is. Today, I would probably still keep docs.asciidoctor.org because I think asciidoctor.org is going to be more about marketing the community. So for us, there is still a split. Sharing that just to provide some context.

[mojavelinux]

After giving this more thought, we're starting to gravitate towards having two playbooks (i.e., two sites that act in tandem). They would share a UI, but publish to different URLs. One site would publish to jetty.org and the other to either jetty.org/docs or docs.jetty.org. By doing so, it gives you the option to put the docs site either at a subpath or at a subdomain without having to change anything else. But we're still not 100% sure how it will work out. Therefore, we'd like to experiment with it to test its viability.

If we decided to stick with a single playbook, then it would likely be necessary to use an Antora extension to insert the /docs subpath in the URLs for non-ROOT components. This is not something that Antora supports out of the box, and we're still trying to wrap our head around how it would even work if it did. But it's something an extension can easily do.

[jmcc0nn3ll]

If we split out docs into a separate playbook, then Javadoc would be the same sort of deal, right?

[mojavelinux]

Yes, I think if we split it, there's almost no reason to tie the Javadoc into the Antora build (at least not the main one). It could just be published using a separate process to its own domain. (If we wanted some UI over it, there'd probably be a way to run it through Antora, but that would be a third playbook with its own cadence). Still a bit early to tell and experimentation will reveal the best path in time.

[mojavelinux]

We've done some more thinking about how to handle the division/relationship between the home pages and the docs. In order to help us resolve which path to take, we've prepared two proposal branches.

• Proposal A (single site and playbook) - https://github.com/opendevise/jetty.website/tree/url-strategy-proposal-a
• Proposal B (two sites and playbooks, shared UI) - https://github.com/opendevise/jetty.website/tree/url-strategy-proposal-b

The first proposal branch is based on a single Antora playbook. We've added a simple Antora extension that pushes the docs components (contributing-guide, jetty, etc) into the docs subfolder. This is just a manipulation of the output path and URL of the pages (something Antora affords us). The result is that documentation pages will be published to a URL such as https://jetty.org/docs/jetty/12/operations-guide/ (notice the addition of /docs after the domain).

(You'll notice on the Camel site, which uses the same single Antora playbook setup, that docs components are not under the /docs folder but rather at the top level).

The second proposal branch uses two Antora playbooks, one that builds the home pages and the other that builds the docs. The result is that documentation pages will be published to a URL such as https://jetty.org/docs/jetty/12/operations-guide/ without any additional work. We've add a second ROOT component (located in the docs-home folder) that provides the documentation start page for use in the docs playbook, removing this page from the ROOT component for the home playbook (this allows this page to access the other docs components). We added an Antora extension that merges the sitemaps of the two sites (so a crawler can find all pages). There's also some tweaking of the UI so links in the topbar nav resolve.

The second proposal opens the door for being able to move the docs to a subdomain (e.g., docs.jetty.org), whereas the first proposal does not provide that option (though choosing the first option doesn't lock you into that restriction forever).

Now that we have these two branches created, we're going to study them to better understand the conceptual challenge we face and how to make a decision about which strategy to choose.

[jmcc0nn3ll]

(You'll notice on the Camel site, which uses the same single Antora playbook setup, that docs components are not under the /docs folder but rather at the top level).

Camel has a page at camel.apache.org/docs/, which you then select the component, I guess, which then removes /docs and drops back to that component camel.apache.org/camel-core/, which has its page, then when you select reference docs it sends you to camel.apache.org/camel-core/reference. That is a bit much for us since we don't have discrete components with separate documentation.

What we have are versions and documentation names. The 10, 11, 12 versions of the operations guide, programming guide, the unversioned contribution guide, and the singular Jetty 9 book.

We must figure out the right URL for these different beasts and stick with it for eternity. :)

Perhaps it would help to look at it from a URL perspective first.

• Proposal A
  • jetty.org/docs - a description of what info is where to make the right decision with a search bar I suspect
  • jetty.org/docs/jetty/11/operations - the root of the operations guide for jetty 11
  • jetty.org/docs/jetty/12/programming - the root of the programming guide for jetty 12
  • jetty.org/docs/jetty/9 - the root of the Jetty 9 glob o' book

The extra jetty in that URL is a bit redundant, and honestly, this whole thing is making me hate the breakdown of things into an operations guide and a programmer guide. We may need to think about smashing everything together again. I suspect @sbordet will not like that, though. :) Since we will have a search embedded in this, it may also make the breakdown redundant.

Another question is what should be served at jetty.org/docs/jetty/11/ or jetty.org/docs/jetty/, is that just a redirect back to /docs?

• Proposal B
  • docs.jetty.org - a description of what info is where to make the right decision, with a big old fat search bar
  • docs.jetty.org/11/operations - above
  • docs.jetty.org/12/programming - above
  • docs.jetty.org/9/ - above

I removed the /jetty/ because it looks cleaner. I don't know where I lay on this, but ultimately I think our guiding factor for the decision is which is weighted better for SEO, if there is a favorite... I asked @joakime about that and he said he didn't think it mattered anymore, just that stable URL's are king.

Let's not forget Javadocs. Should those not factor into this discussion at all, should they be their own component and build/deployed with the site? Should we say shove it, and dump them on javadoc.jetty.org? I mention them in case they influence thinking at all.

Anyway, my immediate thoughts reading your update.

To be clear, I am mentioning a couple of things here that are not necessarily under contract and not with the expectation they get done under one by you...but purely as a part of the overall discussion of bringing everything under one roof.

[mojavelinux]

Camel has a page at camel.apache.org/docs/, which you then select the component, I guess, which then removes /docs and drops back to that component camel.apache.org/camel-core/, which has its page, then when you select reference docs it sends you to camel.apache.org/camel-core/reference. That is a bit much for us since we don't have discrete components with separate documentation.

To help understand what's going on there, docs.adoc is a page in their ROOT component, which becomes /docs/ (the translation from docs.adoc to /docs/ is done by the extension style setting). Once outside the ROOT component, the component name is used in the URL, which is why you shift to /camel-core/.

As proposal A demonstrates, it's easy enough to convince Antora to scope the document components to the /docs/ folder by prepending a prefix to the path/URL. In the case of Camel, this would result in /docs/camel-core/ instead. I think when the docs are co-hosted with the home site (the site with the home pages), it should be done this way to make it clear when you cross into the docs section. It may also make redirects easier down the line.

[mojavelinux]

What we have are versions and documentation names. The 10, 11, 12 versions of the operations guide, programming guide, the unversioned contribution guide,

That's not how I would explain it. What you have is a single docs component named jetty that has versions. The operations and programming guides are modules, which is a book-like subdivision of the docs for a project.

I want to assure you that's it perfectly normal in an Antora site to have book-like divisions in a version of the docs, such as operations guide and programming guide. That's not weird. Sarah did a brief analysis of the content of these two guides and determined that there's virtually no overlap between them and that they are each tailored towards a specific audience. So we really don't see an urgency to combine them. We could extract certain chapters into their own book-like modules if the content of those chapters is meant for any audience (such as start and migration).

If that doesn't assure you, and you still want to merge these guides, you'll need to complete that work on all three branches (10, 11, and 12) before we start migrating anything. We can't have the structure fundamentally changing while we're trying to migrate. (Though, like I said, the migration can promote certain chapters).

[mojavelinux]

After giving these two proposals a lot more thought, we've come to the recommendation to select proposal A, a single site/playbook with the docs (in published form) scoped to a subpath (e.g., /docs). There are numerous reasons we came to this recommendation, but it all boils down to simplicity. You often see teams use a subdomain for docs to give them their own space to work in the case when the main site is managed by another group. Coordinating updates to a site that another group manages can be very challenging, not to mention slow and frustrating. The subdomain allows the docs team to work independently.

You don't have this situation. Instead, you're aiming to create an integrated site from scratch (shared branding, shared topbar nav, etc). We don't want to introduce an arbitrary division that isn't there to begin with. That division comes with an overhead (and possibly SEO consequences). You end up having to manage two sites, potentially with two different pipelines, and coordinate references between them. It's hard.

Given that you're just starting to use Antora, this seems to us like we'd be throwing you into the deep end before you even learn how to swim with it (just look at how many changes were needed to get proposal B to work). Simply put, it's just too complex. In time, you may decide to introduce the jetty.org/docs.jetty.org division. That's easy to do with the help of a URL rewrite engine (in fact, we did exactly that in our own docs). But if you split now, you always have to maintain two sites, even if you decide to combine them again (since you have to redirect away from the second site).

Assuming we use a subfolder for docs, what you need to decide is which URL structure you prefer:

1. /jetty/12/ - use the component name by itself in the URL; this is the default
2. /docs/jetty/12/ - prefix the component name in the URL with docs/; this is what the extension does
3. /docs/12/ - replace the component name "jetty" with "docs"; this would only work if you never anticipating have other docs projects; we can modify the aforementioned extension to apply this customization

Another question is what should be served at jetty.org/docs/jetty/11/ or jetty.org/docs/jetty/, is that just a redirect back to /docs?

Don't worry about these redirects as that's something Antora already provides (specifically the start page and latest version strategy). Just focus on the pattern of the URL structure I outlined above.

We must figure out the right URL for these different beasts and stick with it for eternity.

No you don't. URL rewrite engines afford you the option to restructure URLs in the future without breaking links. And Antora's page aliases allow you to rename or move pages within a site without breaking URLs too.

Let's not forget Javadocs.

We aren't, but it's orthogonal to the topic at hand. We can address that in a separate issue.

[jmcc0nn3ll]

Ok, I am waffling on the correct URL for the docs now. @sbordet could you chime in?

I dislike the redundant /jetty/ in both 1 and 2 however you make a good point in 3 about never having another doc product. If we decided sometime down the road to split out the documentation for some aspect of Jetty it could be important to retain this ability.

The example that comes to mind right now is we are just at the beginning stages of dealing with the split we have made for a core jetty experience and the ability to have multiple EE environments resting on top. It isn't under consideration now, but what happens if we decided to fix the common core of Jetty to a version and then separately release the EE versions. Or if we took that core of Jetty and built on top a webservices or reactive streams distribution. We have dabbled with lots of things over the years and I am leery of making a decision now that limits our ability to cleanly present documentation. What if we were to bring CometD or some other project under the jetty umbrella some day?

This has me leaning pretty heavily towards the default option #1 now.

Question: If we wanted to retire a version of jetty like 9 sometime down the road and we wanted to make that clear in the URL, how would we convert that URL to something like /archive/jetty/9?

[mojavelinux]

This has me leaning pretty heavily towards the default option #1 now.

I think it should at least be 2. The website doesn't just contain docs, so I think it's important to delineate where the docs live within the website. Otherwise, everything is crashing the top-level.

The redundancy of the project/component name is extremely common. We even have it in the Antora docs. See https://docs.antora.org/antora/latest/ Without it, you end up having a really hard time if you ever add another docs set, like CometD for example.

how would we convert that URL to something like /archive/jetty/9?

URL rewriting is incredibly powerful and can always be used to remap existing URLs, either permanently or temporarily. However, the better you partition things initially, the easier it becomes to write those rules in the future. But, with enough entries, every URL can become a different URL at any time. You never have to settle for a broken URL that you don't want to break. And an Antora extension can manipulate both the URL (move it to /docs-archive/jetty/9) and set up the redirect to it.

[joakime]

I dislike the redundant /jetty/ in both 1 and 2 however you make a good point in 3 about never having another doc product. If we decided sometime down the road to split out the documentation for some aspect of Jetty it could be important to retain this ability.

I see the extra /jetty/ as useful in the long run.

We have a few projects on github.com/jetty-project/ that could use to be documented too, and are not part of the github.com/jetty/jetty.project tree, but deserve to be on https://jetty.org/ too.

We might have entries like /jetty-async-client/ or /jetty-load/ or /jetty-test-helper/ or /jetty-alpn-api/ etc ...

[mojavelinux]

Also keep in mind that the "jetty" name in the URL could be renamed to "jetty-core", "core", or "jetty-server". It doesn't have to be just "jetty". However, you will want to pick something and stick with it as that name is used in cross-project xrefs.

[sbordet]

I'm fine with any solution, as I am sure we will change our minds back and forth many times, so whatever simpler for now is best for me.

[mojavelinux]

See #12.