Docs: Change URL pattern to not break URLs with every patch release

[jpmckinney]

The current situation is:

1. Version 1.3.0 is released. Docs are at https://docs.ted.europa.eu/eforms/1.3.0/index.html
2. Version 1.3.1 is released. Docs are at https://docs.ted.europa.eu/eforms/1.3.1/index.html. URLs with 1.3.0 now 404.

This is rather annoying as we constantly need to update our URLs (we regularly refer to eForms documentation in our own documentation).

There are two easy options:

1. Publish the 1.3 series at https://docs.ted.europa.eu/eforms/1.3/index.html In most patch releases (or maybe even all to date), there is no page that is added or removed, and no page that retains the same name yet fundamentally changes content. Even so, this option handles those scenarios gracefully. Switching to this option comes at no new cost, since, to date, you have already been breaking all the URLs with every patch release. This option is better than the above, because:
   1. URLs don't break.
   2. If a page is removed, the user gets a 404, just like above.
   3. If a page's content changes such that it is fundamentally different, it should be renamed. In this way, a user who linked to some page that was part of 1.3.0 won't load a page that is totally different when 1.3.1 is published. I'm sure you do this already (if it ever occurs), and so it is not any additional overhead for this proposal.
2. Keep the earlier 1.3.x documentation online. Honestly, I don't understand why it's removed from the internet entirely.

And there is one more difficult option:

3. Set up redirects. This requires a little more effort, but is also totally doable.

[rousso]

Hi @jpmckinney,

Try https://docs.ted.europa.eu/eforms/latest :)
For example https://docs.ted.europa.eu/eforms/latest/fields/index.html

1. I will think about your idea. The problem with it, is that we may need to totally hide the patch number from everywhere in the site, which is something I am not very enthusiastic about. But I think there is a way around my problem that can also solve your problem too.

2. This is not a good solution for the specific issue.

3. The "/latest/" URL that I proposed above, is actually a redirect. I does not work on all pages yet but we will try to add it in every page we missed it. In general if we ever decide to move a page, we will use redirects. Currently we are in the process of migrating to Antora 3.x. When we are done with that we will revisit the "/latest/ redirect idea and try to make it universal.

Regards,
Yannis

[jpmckinney]

Oh, and I just tried to open the result on the elements.html page for "BT-777" in 1.4.1, but I get page not found...

[rousso]

Hi again,

The elements page is not needed. I removed it a couple of days ago.
Like the all-in-one page, the elements page is just a duplication of content.

The only reason I did not yet remove the all-in-one page is because I am still thinking about what you said and trying to figure out what I can do to keep us both happy. :) My problem is that keeping the all-in-one page is against all design principles for the docs website.

Did you try the search? We now use Algolia for search which is state of the art. What is your problem with the search? Is there something specific that bothers you with it, is or it that you generally prefer to click Ctrl-F and use find in page?

Let me know :)

[rousso]

Oh, and I just tried to open the result on the elements.html page for "BT-777" in 1.4.1, but I get page not found...

I just checked and indeed the search index was not updated.
I asked our devops engineer to correct the indexing script.

[jpmckinney]

Did you try the search?

I described the significant UX issues above.

I know of Algolia; for example, https://getbootstrap.com/ uses it. However, in their implementation, actual content is highlighted in result snippets. For the eForms SDK, it's only headings that seem to get highlighted.

Bootstrap also only returns results from the version being viewed (good); they don't return results from all versions like eForms SDK does (not helpful).

That said, Bootstrap's implementation has the same issue of it being impossible to follow multiple results without re-entering the search terms, retrieving results, and clicking a new result. It would be better if the search modal stayed open after opening a result in a new tab. Edit: It seems if I right-click and open a new tab via the context menu, then the modal stays open. If I ctrl-click (or cmd-click) a result, then the modal closes.

[rousso]

Ok. Thanks for the feedback.
I will see what I can do with the ideas you provided.
I am keeping all-in-one for the moment. I removed it from the search results though so that we don't have duplicates there.
Thank you @jpmckinney

[jpmckinney]

Ah, great, I will try that. In my case, I will always be tracking latest. If any folks need to track earlier major/minor versions, option 1 might still be a good idea.

[rousso]

Hi again @jpmckinney,

Your suggestion has been implemented. Try it in th docs website.
So thank you for it!!

• Only major.minor version number is now in URLs.
• The "latest" redirect works on all pages.

Cheers,
Yannis

[jpmckinney]

Thank you! 🚀