[hibernate-dev] People can't find our docs

[Guillaume Smet]

Hi,

When we search for Hibernate/Hibernate Search issues, Google send
people to *very* outdated docs.

For instance, searching for %1$s gets me to %2$s:
- hibernate collection element ->
https://docs.jboss.org/hibernate/orm/3.3/reference/en/html/collections.html
(yes, *3.3*)
- hibernate search facet ->
https://docs.jboss.org/hibernate/search/4.5/reference/en-US/html/search-query.html

These versions of our docs are very well indexed by Google as they
come up before stack overflow but it's really a bad thing to get
people directed to very old versions of our documentation.

Do we have people at RH working on this sort of things who could help
us defining a good strategy to improve that? Did anyone already take a
look at this?

When I was contributing to PostgreSQL, the subject was discussed at
length and they didn't find a good solution at the time to get Google
to preferably link to the last version. Using canonical urls for
instance requires you to regenerate all the old docs when you have to
point to another URL.

They finally decided to integrate links to all versions at the top of
each doc page: https://www.postgresql.org/docs/9.5/static/sql-syntax.html
.


>From my point of view, here are a few things that might help mitigate the issue:
- have a version of the doc labelled as /current/ (or /stable/) on
hibernate.org. From what I've seen, ORM has a /current/ symlink but
it's currently pointing to the 5.1 documentation and is not used on
the website. We should use this link every time we link to the
documentation (especially on SO).

- Maybe we could try to map the old URLs to the new ones by doing
something similar to what PostgreSQL does but dynamically with jQuery.
We could inject it in the old documentation with something like
http://httpd.apache.org/docs/2.2/mod/mod_substitute.html if we can get
this enabled on docs.jboss.org.

- our doc URLs are now named chNN.html which is not very future proof.
Did we have issues keeping the semantic ones? I suppose it's related
to the asciidoc migration? It would be a good way to keep more stable
URL.

- btw, is there a reason why we only generate the html_single output
for Hibernate ORM?

Thoughts, opinions, ideas?

-- 
Guillaume