google-ability

[dalexander]

Googling anything about SWIG almost invariably leads you to ancient documentation from version 1.3... example screenshot attached. It would be nice if something could be done to move more recent documentation to the top of google searches...

[wsfulton]

If some web ranking guru can explain a simple fix, we can try implement.

[ojwb]

I've noticed this effect too - it's definitely annoying.

It will be mostly down to link analysis - there are going to be a lot more links to the Doc1.3 versions out there on the web than to the Doc2.0 versions, and even fewer to the Doc3.0 versions (simply because the older versions have existed for longer), and link analysis algorithms will tend to favour pages with more in-links.

We could just mark the old versions not to be indexed (via robots.txt or <meta name="robots" content="noindex">) but that makes explicit searches for older SWIG documentation harder.

I'd suggest we make the latest version always be available at just Doc (to avoid this effect for future release series), put the older versions on new URLs (e.g. Doc-1.3 and Doc-2.0), and redirect Doc1.3 and Doc2.0 - either redirect them to Doc, so that it gets their in-link boost, or redirect them to Doc-1.3 and Doc-2.0 via a page which has <meta name="robots" content="noindex,nofollow"> (so that search engines hopefully don't follow the redirect). Redirecting to Doc seems a better plan to me - it means that the new Doc version should quickly start to rank highly, and almost everyone making such a link isn't going to be intending it to be for a particular SWIG version, rather they're just linking to the URL currently available.

It would also help to add a banner box to each page in the old versions with a note that this is documentation for an older version, and with a link to the equivalent page in the latest, so human visitors know that they have reached an old version. It will tend to boost the page the latest version in link analysis, but I doubt this alone would fix the ranking problem.

[michael-schaller]

IMHO:
+1 for making the newest documentation available under just Doc. The main entry point into the documentation http://swig.org/doc.html needs an update as well. I recommend to make a general link to the newest documentation on top and then a section with links to version specific documentations.

+1 for a banner on top. This could be a static banner for all pages that has a drop down field for the version similarly to the Python documentation. The version list would just contain Newest, 3.0, 2.0, 1.3. This could be problematic though as this could forward to a non-existing page. For an instance if I look at the newest Go documentation and then select 1.3 I would get a 404. So the 404 page should be updated as well and contain the same banner to select a different version.

-1 for changing the robots.txt because some people are stuck with older versions and this would break searching for older versions specifically.

-1 for redirecting to the newest documentation. Older versions sometimes have quirks and redirection would break links to these quirks if someone specifically documented them in their documentation/source. As an example SWIG 2.0 and earlier doesn't support nested classes. Redirection only for robots would be plain confusing because search results/snippets would often not match the content behind the link and to make matters worse the link could be plain invalid.

[ojwb]

This could be problematic though as this could forward to a non-existing page.

We know the lists of pages for each version, so it's not hard to make the banner avoid offering a page which doesn't exist in an older version. I don't know of a case where we've renamed a page, but that wouldn't be hard to handle either - there are ~43 pages, so comparing the file lists to find any renames is totally feasible, and a script to add the banners could tailor them to each page as necessary.

Older versions sometimes have quirks and redirection would break links to these quirks if someone specifically documented them in their documentation/source.

This documentation doesn't include anything from the sources (there's no doxygen-like collation of documentation from SWIG source comments).

Note that I'm not suggesting making it impossible to link to a specific version of the docs, but suggesting redirecting existing versioned links (which in most cases are only versioned because there's no option for them not to be - this isn't just an assumption, I've tried a few searches and looked through the results).

This redirection does have a downside, but we should bear in mind that not redirecting also has a downside, and the number of cases where existing links are intentionally to a specific version of the documentation is a tiny minority.

In my experience, most of the SWIG quirks that get fixed were never documented in the first place. Even in a case like yours where the link author intended a specific version, a redirect isn't automatically bad - for example, someone reading an out of date third-party claim that "SWIG doesn't support nested classes" backed up with a link to the 2.0 docs could follow it and see that this was now supported.

Redirection only for robots would be plain confusing because search results/snippets would often not match the content behind the link and to make matters worse the link could be plain invalid.

I've never suggested we should try to do any redirection specific to robots.

[michael-schaller]

We know the lists of pages for each version, so it's not hard to make the banner avoid offering a page which doesn't exist in an older version.

Awesome! :-D

This redirection does have a downside, but we should bear in mind that not redirecting also has a downside, and the number of cases where existing links are intentionally to a specific version of the documentation is a tiny minority.

The problem is that you can't know if a link to a specific version of the documentation is intentional or not if all that is available are versioned links. So your gut feeling tells you that only a tiny minority of links are intentionally to an older version and my gut feeling agrees with that assumption. Nevertheless I wouldn't redirect automatically because of two reasons:

1. In reality there is often more than one SWIG version in use/available. Just look on Debian and you'll see that Debian Wheezy (oldstable; still supported until May 2018) only has SWIG 2.0.7 and that Debian Jessy (stable; supported until April 2020) has SWIG 2.0.12 and SWIG 3.0.2. So if you'd maintain a software that has to run on Debian Wheezy then you'd also stick to SWIG 2.0 until these 3 conditions are met:
   • SWIG 3.0 is available on all supported distributions.
   • SWIG 3.0 is stable/bug-free enough on all supported distributions. Debian Jessy (SWIG 3.0.2) might not be stable/bug-free enough.
   • You actually have time and the resources to port your software to SWIG 3.0. You don't necessarily want to spent time on software that is in low-maintenance mode if you can work on something new and more interesting. ;-)
2. Automatically redirecting to the newest version of the documentation is IMHO dangerous for version-specific links in TODO/FIXME comments. In the best case it is weird and in the worst case the redirection is so confusing to somebody that the TODO/FIXME comment gets removed without properly resolving it.

If you only use the newest SWIG version I think an automatic redirect to the newest version is awesome. I don't know though how many developers are stuck with an older version for whatever reason and an automatic redirect would only annoy them. So I think a warning in the banner if someone looks on outdated documentation would be more appropriate...

I've never suggested we should try to do any redirection specific to robots.

Olly, I just mentioned the implications for the sake of completeness and before someone starts discussing this very bad idea. I didn't think that you'd wanted to go down that road. So sorry if I've offended you with that comment.

[wojdyr]

Maybe use sitemap to assign different <priority> to different versions? Like in http://spark.apache.org/sitemap.xml

[ojwb]

Sounds good, assuming it actually works. Worth trying before anything more complex anyway.

[wsfulton]

Agreed, seems plausible. If a patch appeared with the appropriate changes I can help test it out. Any idea how long we need to try it out for before seeing a positive effect?

[ojwb]

Moved to the www repo since this is about the website and that's where any fix needs to be made.

I had a look at a sitemap, but it seems to need an individual entry for every single URL which seems cumbersome. I guess it would need to be generated by a script really.