Re: [hibernate-dev] People can't find our docs
Hi Guillaume,
yes I'm aware of the issue; we discussed it before, I think on this
same mailing list but maybe it was during our last meeting.
We really need to fix that metadata; Stefania (my partner) is an SEO
consultant and is shocked at how bad we do with this; apparently we
are a funny example in her office but at least we're not the worst :)
The problem is we can't change the headers as we don't control the
Apache httpd configuraion on the documentation server, so the
alternative is we'd need to rsync those docs locally, insert the right
changes in the static files of the docs, and push them back.
Needs a volunteer to find some time for this.
Also related to SEO I recently opened some issues on our WEBSITE
project, these should be easier to fix as it's directly under our
control:
- https://hibernate.atlassian.net/browse/WEBSITE-461
- https://hibernate.atlassian.net/browse/WEBSITE-460
- https://hibernate.atlassian.net/browse/WEBSITE-459
I've assigned them to Davide as he's usually quick with such things
but anyone is welcome to take some.
The metadata issue on the docs server is probably the most urgent /
valuable though.
Thanks,
Sanne
On 19 July 2016 at 13:24, Guillaume Smet <guillaume.smet(a)gmail.com> wrote:
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
.
>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
_______________________________________________
hibernate-dev mailing list
hibernate-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hibernate-dev