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

[Guillaume Smet]

Iiiik, remove the .local suffix in the domain for the first example!

On Thu, Jul 21, 2016 at 1:33 PM, Guillaume Smet
<guillaume.smet at gmail.com> wrote:
> 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