hackage-server

hackage-server copied to clipboard

Ticket #61 seems to claim that a solution would fix the problem where search engines give results that link to old versions of documentation. Though a fix was implemented 5 months ago, the problem is still occurring. As of today, the first link on both Google and Bing link to mtl-1.1.0.2, which is very old. The problem is similar when searching for control.monad.state, except that the latest version doesn't even appear on the first page of Google results. It is annoying even when I remember to check the version before reading the docs, and extremely confusing when I forget to check. Can something more be done to solve this issue?

As a simple work around for this could it just include some indication on the page that this is not the latest version of the docs and include a link to the latest?

Something like this mockup would be nice:

This reddit thread outlines a possible solution.

I think there's two issues here:

• Google links to old versions of package documentation
• When looking at package documentation you can't tell if you're looking at the latest version

Solving the first one would be great but it still doesn't solve the second use case.
Although, I've only just realized that you can get to the latest with two clicks "Contents" at the top right, and then the latest version number on the contents page.

@AshyIsMe I agree that these are separate issues, and that adding a link that stands out from the rest of that list (like bold and green) is a good idea regardless of what can be accomplished with search engines. It also serves as a temporary fix to the search engine problem, but I really feel that the search engine issue should be addressed as well (that is what the original question was about).

As for the Contents link:

1. It's two clicks, except when it's not
2. You still have to remember to do it!

So I have some code now that can dynamically insert JS on our served haddock pages. The idea is this JS could test if there's a newer version of the docs, and give a warning and a link (say, in a banner at the top of the page). Cc: @jfarid27 who said he can help with writing this JS :-)

the work in progress branch is at https://github.com/haskell/hackage-server/tree/rewrite-docs and the stub js file to be amended is here: https://github.com/haskell/hackage-server/blob/rewrite-docs/datafiles/static/hackage-haddock.js

Just wanted to inform you that this has been annoying me for a long time. It is great to see that there will be a solution coming up. I also would like to suggest adding a warning, something like:

There is a newer version of this package available.

Also, the python documentation directly adds a list of python versions that you can jump to (without having to go to contents and then to the newest version).

from the other thread -- the warning for django releases seems like it has good ux: https://docs.djangoproject.com/en/1.7/intro/tutorial01/

I like the django UX just fine, though it would be nice to add a "click here for the latest version", which would try to take you to the same page in the latest version if possible, or just the hackage main page for the library otherwise. For example, if you go to https://hackage.haskell.org/package/mtl-1.1.1.1/docs/Control-Monad-Reader.html, a popup would redirect you to https://hackage.haskell.org/package/mtl-2.2.1/docs/Control-Monad-Reader.html, or to https://hackage.haskell.org/package/mtl-2.2.1 if Control.Monad.Reader didn't exist in the latest version of mtl.

Would it be possible to serve a latest page for each package that redirects to/serves the newest version? The benefit of this is better SEO, if there's a concrete latest URL for a package, then google will be more likely to serve that version over older releases.

e.g.

https://hackage.haskell.org/package/containers-0.6.5.1/docs/Data-Map.html -> https://hackage.haskell.org/package/containers-latest/docs/Data-Map.html

The actual version would ideally still be displayed in the navbar for module documentation.

A latest tag may not even be necessary, seeing as https://hackage.haskell.org/package/<packagename> already links to the newest version. It seems possible to extend module docs to follow this pattern too.

What would you propose linked to this latest url? Also, if that url is a redirect, I don't think google will prefer the redirect over its target...

One general issue is that what modules are available may change between versions of a package.