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

[Sanne Grinovero]

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 at 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-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
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev