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

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-q... 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 . - 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