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

[Emmanuel Bernard]

Nice,

Should we add a X or I got it button to remove this nagging when I have
to read and stay on the old doc?

If that piece of code is in the xsl, how will it work when the doc is in
the distribution?

How screwed are you if we stop using these stylesheet and say embrace
the Asciidoctor default style?

On Thu 2016-07-21 13:33, Guillaume Smet 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
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev