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

[Guillaume Smet]

Hi all!

So here is a status of what I did:
- I updated the /stable/ link of ogm from 3.0 (cough, cough) to 5.0:
http://docs.jboss.org/hibernate/stable/ogm/reference/en-US/html/: we
need to include this in our release process.
- I updated the /current/ symlink of ORM to point to 5.2 instead of
5.1: it needs to be integrated in the release process; (the /stable/
link uses the /current/ symlink so it's also fixed)
- I removed the docs for OGM 3.0 as they were a copy of the doc of OGM 4.2

Next, I applied some magic to 2 old versions of OGM and Search so that
you can check everything is OK for you before I generalize it:
- Add meta description and keywords
- Add a canonical link to the /stable/ single html version
- Add a piece of Javascript to warn the user and propose to redirect
him to the best possible place of our last stable release
documentation

See the 2 examples here:
http://docs.jboss.org.local/hibernate/ogm/4.1/reference/en-US/html/ogm-architecture.html
(scroll to see the hash tracker in action)
http://docs.jboss.org/hibernate/search/4.2/reference/en-US/html/search-architecture.html

See the current code and descriptors here:
https://docs.jboss.org/hibernate/_outdated-content/

The script and the descriptors work for all existing versions of the
OGM and Search doc.

The marker to include in the docs looks like that:
<script src="//code.jquery.com/jquery-3.1.0.min.js"
integrity="sha256-cCueBR6CsyA4/9szpPfrX3s49M9vUU5BgtiJj06wt/s="
crossorigin="anonymous"></script>
<script src="/hibernate/_outdated-content/outdated-content.js"
type="text/javascript"></script>
<script type="text/javascript">$(document).ready(function() {
HibernateDoc.OutdatedContent.install("search"); });</script>

(I'm using a CDN but maybe we should host jQuery on docs.jboss.org?)

The script is capable to redirect either to the multi page version
(using the redirects declared in the JSON file: it automatically
cumulates the redirects from version X to version Y so we don't need
that much metadata) or to the single page version by leveraging the
anchors and hashes. For now, I decided to push the user to the single
page version as it's the one we use for the canonical link but we can
of course discuss it. Note that I add a ?v=X.X parameter to be sure
the user is redirected to a fresh version of the corresponding
/stable/ page and not a cache. I had the issue a couple of times.

Next if you like it:
- generalize it to all the existing versions of the docs, sed FTW
- modify the Hibernate XSL stylesheets to include it in the newly generated ones
- probably modify our website so that the stable release points to the
/stable/ link to the docs
- do the same for Validator

@ORM: interested in me pursuing this for ORM too? It will probably be
a lot more work as the structure of the docs got changed a lot.

Comments, opinions, thoughts welcome.

-- 
Guillaume

On Wed, Jul 20, 2016 at 12:06 PM, Davide D'Alto <davide at hibernate.org> wrote:
> I'll try to apply these changes on Friday.
>
> Davide
>
> On Tue, Jul 19, 2016 at 11:53 PM, Guillaume Smet
> <guillaume.smet at gmail.com> wrote:
>> Hi Sanne,
>>
>> Thanks for your feedback. I was pretty sure I hadn't all the history!
>>
>> Getting Google to prioritize our latest doc is probably a long time goal.
>>
>> I played a bit with jQuery to suggest to the user to go to the latest
>> stable. Note that I only took into consideration the page for the time
>> being and didn't consider the anchor but it should be easy to add it
>> if we think it's worth it (it's a lot more work on the json descriptor
>> though).
>>
>> The following command for each version is all that is needed:
>> sed -i 's@</body>@<script
>> src="http://code.jquery.com/jquery-3.1.0.min.js"
>> integrity="sha256-cCueBR6CsyA4/9szpPfrX3s49M9vUU5BgtiJj06wt/s="
>> crossorigin="anonymous"></script><script
>> src="/hibernate/search/outdated-version.js"></script></body>@' *.html
>> (or a find -exec to do it on all the versions at once)
>>
>> I attached the global json descriptor and the js file (with a .txt
>> extension as it didn't pass the mail filter). Both should be added to
>> /hibernate/search/. Note that I only did the work for version 4.5 in
>> the json descriptor. The work for other versions would mostly be a
>> copy/paste.
>>
>> I also attached a screenshot of how it looks like. Nothing fancy but
>> we can do whatever we want.
>>
>> Note that I only targeted the multi page HTML output as it was the
>> most interesting to prototype.
>>
>> When we release a new version, we would have to update the descriptor file.
>>
>> Comments?
>>
>> --
>> Guillaume