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

[Guillaume Smet]

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

On Tue, Jul 19, 2016 at 2:39 PM, Sanne Grinovero <sanne at hibernate.org> wrote:
> 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
-------------- next part --------------
$(document).ready(function() {
	$.getJSON('/hibernate/search/documentation.json', function (json) {
		var currentUrl = window.location.pathname;
		var match = new RegExp('^' + json.pattern.replace('${version}', '([^/]+)').replace('${page}', '(.+\\.html)') + '$').exec(currentUrl);
		if (match.length != 3) {
			return;
		}
		var currentVersion = match[1];
		var currentPage = match[2];
		var currentHash = window.location.hash;
		
		if (currentVersion == json.stable || currentVersion == json.development || currentVersion == 'stable') {
			return;
		}
		
		var redirectPage;
		if (currentVersion in json.versions && currentPage in json.versions[currentVersion].redirects) {
			redirectPage = json.versions[currentVersion].redirects[currentPage];
		} else {
			redirectPage = '';
		}
		stableUrl = json.pattern.replace('${version}', json.stable).replace('${page}', redirectPage + currentHash);
		$('head').append('<style type="text/css">' +
			'.outdated-content {' +
			'	position: fixed;' +
			'	bottom: 0;' +
			'	left: 0;' +
			'	text-align:center;' +
			'	width:100%;' +
			'	padding: 20px;' +
			'	background-color: orange;' +
			'	background-color: #ffbc3b;' +
			'	border-top: 1px solid orange;' +
			'	font-weight: bold;' +
			'	font-size: 20px;' +
			'	color: white;' +
			'	text-shadow: 0 1px 1px rgba(85, 85, 85, 0.55)' +
			'}' +
			'a.version {' +
			'	border: 1px solid #AAA;' +
			'	border-radius: 4px;' +
			'	background-color: #BBB;' +
			'	padding: 3px 8px;' +
			'	color: white;' +
			'	text-shadow: 0 1px 1px rgba(85, 85, 85, 0.55);	' +
			'	text-decoration: none;' +
			'}' +
			'a.version:hover {' +
			'	background-color: #CCC;' +
			'}' +
		'</style>');
		$('body').append('<div class="outdated-content">This content refers to an outdated version of ' + json.project + '. Go to latest stable: <a href="' + stableUrl + '" class="version">version ' + json.stable +'</a>.</div>');
	})
});