[gmx-developers] web site/documentation improvements [ fork of Re: Gerrit, Jenkins and website back up ]

[Vedran Miletić]

19.09.2017 u 12:04, Szilárd Páll je napisao/la:
> On Mon, Sep 18, 2017 at 5:07 PM, Erik Lindahl <erik.lindahl at gmail.com
> <mailto:erik.lindahl at gmail.com>> wrote:
> 
>     Hi,
> 
>     The drawback I see with including patch levels is that it leads to a
>     massive amount of different Google hits that should be identical.
> 
> 
> Indeed, that is an issue right now as we only have patch-level links! 
>  
> 
>     Instead, I think it's better to enforce that patch level versions
>     should *really* only be patches that fix specific bugs, never any
>     new functionality (not even support for a new processor or
>     performance tweaking).  We are creating an uphill battle for
>     ourselves where the real release (2017 right now) is delayed because
>     we yet again keep having lots of changes in 2016 (no matter how nice
>     those changes are per se!)
> 
> 
> I don't think that's related to the discoverability of the docs, is it?
> Also, as far as I recall, such tweaks (e.g. the AVX512 or Volta related
> change) did not require extra documentation (and to be honest these
> aren't really what are delaying the releases, but that's another topic).
>  
> 
>     So, wouldn't it make more sense to only have documentation for the
>     actual released versions, not separate it into patch levels?
> 
> 
> I think most of the differences between documentation related to patch
> level versions is either tweaks, improvements, or additions of what's
> been missing. Therefore, a single URL per release seems reasonable to me
>  
> 
> 
> 
>     Cheers,
> 
>     Erik

I would keep all of the documentation copies, we just need to decide on
<link rel="canonical"> [1] policy that would work. I believe that
something like

2016.* -> canonical URL to 2016
5.1.* -> canonical URL to 5.1

Then patchlevels won't affect the documentation location, and hopefully
Google indexing will be faster than our users' upgrades. If I understand
canonical URLs properly, we could go further and set

2016 -> canonical URL to current
5.1 -> canonical URL to current

so current gets indexed and appears first all the time in the search
results.

That would mean that at every point the latest stable patchlevel release
would exist in three places, while the previous stable patchlevel would
exist in two.

Regards,
Vedran

[1] https://en.wikipedia.org/wiki/Canonical_link_element

-- 
Vedran Miletić
vedran.miletic.net