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

Tue Sep 19 12:04:35 CEST 2017

On Mon, Sep 18, 2017 at 5:07 PM, Erik Lindahl <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
>
>
>
> On Mon, Sep 18, 2017 at 3:26 PM, Szilárd Páll <pall.szilard at gmail.com>
> wrote:
>
>> Hi,
>>
>> This discussion seems to have ended up high and dry, so let me revive and
>> repeat a few specifics.
>>
>> - Discoverability: as Vedran and I proposed, let's create URLs to the
>> latest and each major release instead of forcing users to edit the search
>> results' outdated URLs (or to have to clock through menus), i.e.
>> http://manual.gromacs.org/documentation/current/index.html ->
>> http://manual.gromacs.org/documentation/2016.4/index.html
>> <http://manual.gromacs.org/documentation/2016.3/index.html>
>> http://manual.gromacs.org/documentation/2016/index.html -> h
>> ttp://manual.gromacs.org/documentation/2016.4/index.html
>> <http://manual.gromacs.org/documentation/2016.3/index.html>
>> http://manual.gromacs.org/documentation/5.1/index.html
>> <http://manual.gromacs.org/documentation/2016/index.html> -> ht
>> tp://manual.gromacs.org/documentation/5.1.5/index.html
>> <http://manual.gromacs.org/documentation/2016.3/index.html>
>>
>>
>> Additionally, could we please make gromacs.org respond with the www?
>>
>> Cheers,
>> --
>> Szilárd
>>
>>
>> On Thu, May 18, 2017 at 6:31 PM, Szilárd Páll <pall.szilard at gmail.com>
>> wrote:
>>
>>> Thoughts got stuck as draft, and Vedran's mail reminded me about it -- I
>>> had more or less the same suggestion to update a few fixed URLs and link
>>> the versioned pages.
>>>
>>>
>>> On Wed, Mar 22, 2017 at 1:50 PM, Mark Abraham <mark.j.abraham at gmail.com>
>>> wrote:
>>>
>>>> Hi,
>>>>
>>>> On Wed, Mar 22, 2017 at 12:39 PM Szilárd Páll <pall.szilard at gmail.com>
>>>> wrote:
>>>>
>>>>> Hi,
>>>>>
>>>>> The one thing I'd hope we avoid is ending up with an empty gromacs.org for
>>>>> months. It might be tempting to just leave a note what content will be up
>>>>> "soon", but it would be a PITA for users to have to old page is nuked
>>>>> without moving all important information over. Of course "important" can be
>>>>> defined liberally (especially on a late Friday night).
>>>>>
>>>>
>>>> If people want things to happen, then please get involved here:
>>>> https://redmine.gromacs.org/projects/gromacs/wiki/Docu
>>>> mentation_migration. I suggest that porting a page is more useful than
>>>> adding links to 20 pages that someone hopes that someone will port :-)
>>>>
>>>
>>> Maybe I have missed it, but has this been announced anywhere?
>>>
>>>
>>>>
>>>> I guess we don't have page stats on the old wiki? (We really should
>>>>> have on the new site BTW.)
>>>>>
>>>> >
>>>>
>>>>> One page that I know is important given that it's in the top 1-3
>>>>> Google results for searches like:
>>>>> "gromacs parallel"
>>>>> "gromacs MPI"
>>>>> "gromacs GPU"
>>>>>
>>>>
>>>> Yeah, but they are things that only some people search for, and make
>>>> sense going to an overview page on the website that provides links to
>>>> version-specific detail as appropriate. How to run mdrun and what it can do
>>>> potentially (and actually) changes with every version.
>>>>
>>>
>>> Just because only "some people" want to know how to run gromacs with
>>> MPI, related relevant information is not important to be discoverable using
>>> a google search just because it's been moved into the repo?
>>> BTW most of this info (like the glossary) changes with a cadence of 8-10
>>> years or the parallelization info with 4+ years, so we're regenerating
>>> pages with minor changes and trashing pagerank.
>>>
>>>
>>> Some aspects of e.g. http://www.gromacs.org/GPU_acceleration make sense
>>>> as an historical blog post (which we can do with WordPress in the future),
>>>> other aspects belong on an overview page, and others perhaps as
>>>> version-specific reporting of e.g. performance results.
>>>>
>>>
>>> Sure, pages like that should in the future be posted either as blog
>>> posts or as announcements clearly marked with a date to indicate that
>>> information that's 3+ years old is not up-to-date.
>>>
>>>
>>>> and it has not been fully transferred:
>>>>> http://www.gromacs.org/Documentation/Acceleration_and_parallelization
>>>>>
>>>>
>>>> Well.. what's missing from all the work we did moving it to
>>>> http://manual.gromacs.org/documentation/2016.3/user-guide/md
>>>> run-performance.html? :-) What user-guide sections should we
>>>> make/alter to fit them?
>>>>
>>>
>>> Last time I checked, many examples and use-cases were left out.
>>>
>>>
>>>>
>>>>
>>>>> Related: need better SEO for the new site and especially the generated
>>>>> documentation sites needs attention. Repo-generated pages takes ages to
>>>>> crawl up in ranking and deploying a new set of pages for every patch
>>>>> release ruins ranking. As a result, most of the google top hits tend to be
>>>>> from the old wiki, old manual pages or at best v5.1 documentation pages.
>>>>>
>>>>
>>>> Pages generated from the source repo should be those which match the
>>>> source version being documented. They are thus exactly those for which we
>>>> do not want to target high SEO for general queries. The SEO optimization
>>>> targets are generally the WordPress pages.
>>>>
>>>
>>> I strongly disagree. People use search engines, not bookmarks to find
>>> things these days. Most browsers do a web search if you type something
>>> (that's not a URL) in the URL bar. Clicking through deep menus/chains of
>>> links of a website is very dated approach and generally not an acceptable
>>> solution if the user searched for "install gromacs howto".
>>>
>>> Googling "gromacs documentation" and "gromacs 5.1 documentation" do
>>>> exactly the intended job - return at first rank the page most specific to
>>>> the query (2016 is a bit strange, google seems to have latched onto the
>>>> beta2 page). We do not want "gromacs performance", "gromacs MPI", "gromacs
>>>> umbrella sampling" or "how to make mdrun fast" searches returning at high
>>>> rank a repo-generated page that matches e.g the 2016.2 release.
>>>>
>>>
>>> Anecdotal, but it illustrates the issue quite well: I regularly have to
>>> edit the URL replacing the version string with something newer just to get
>>> to a recent CMake documentation page because their docs is also generated
>>> under a new URL for every patch release and it has the same issues when
>>> searched with Google.
>>>
>>> Why not make sure that the latest docs quickly become top results in
>>> searches? It is better that "install gromacs howto" (at least in my
>>> incognito window search) returns this instead of linkes mostly to 2016.x
>>> and 5.x user guide pages?
>>>
>>> [image: Inline image 1]
>>>
>>> Not one of the above results points to even remotely up-to-date user
>>> guide. We are doing a disservice to users by not helping them to find the
>>> most up-to-date info using web search (and by letting other random blogs
>>>  take up spots in the top results).
>>>
>>>
>>> It seems like the following might partially solve the issue (but I am no
>>> web/SEO expert so this might not make sense at all):
>>>
>>> * for each new major release update a URL pointing to the "current"
>>> release
>>> http://manual.gromacs.org/documentation/current/index.html ->
>>> http://manual.gromacs.org/documentation/2016.3/index.html
>>>
>>> Additionally, it might make sense to have a "/current-dev" and
>>> "/current-maint" too (for the the previous release in maintenance).
>>>
>>> * for each new major release we could generate a URL that always points
>>> to the latest patch release,i.e.
>>> http://manual.gromacs.org/documentation/2016/index.html -> h
>>> ttp://manual.gromacs.org/documentation/2016.3/index.html
>>>
>>> A brief and general page on e.g. mdrun performance makes sense for users
>>>> (and SEO), but it should direct users on to pages with whatever details
>>>> they actually want, rather than itself containing everything that was ever
>>>> relevant to the topic. :-)
>>>>
>>>
>>> This does not exclude the above, does it?
>>>
>>> --
>>> Szilárd
>>>
>>>
>>>>
>>>> Mark
>>>>
>>>> Cheers,
>>>>> --
>>>>> Szilárd
>>>>>
>>>>> On Tue, Mar 21, 2017 at 8:32 PM, Erik Lindahl <erik.lindahl at gmail.com>
>>>>> wrote:
>>>>>
>>>>> Hi,
>>>>>
>>>>> Yeah, I think we also agreed a long time ago that we should do a
>>>>> massive cleanup. For each type of information there should only be one
>>>>> original location, so any docs that fit in the source should just be
>>>>> present there (and if necessary we'll process it into some sphinx website).
>>>>>
>>>>> Cheers,
>>>>>
>>>>> Erik
>>>>>
>>>>>
>>>>> On Tue, Mar 21, 2017 at 8:26 PM, Mark Abraham <
>>>>> mark.j.abraham at gmail.com> wrote:
>>>>>
>>>>> Hi,
>>>>>
>>>>> Some help migrating documentation from the old website would be most
>>>>> welcome. I have been slowly migrating code-version-specific documentation
>>>>> into Sphinx (e.g. https://gerrit.gromacs.org/#/c/6531/5) but if there
>>>>> are parts people are keen to work on, that would be most welcome (do check
>>>>> http://manual.gromacs.org/documentation/2016.3/index.html to see if
>>>>> it's already there!). Perhaps it would be good to go through pages and
>>>>> comment at the bottom that this has, or should be saved. Pages like Gerrit
>>>>> how-tos should live on Wordpress, however, because they are linked to how
>>>>> Gerrit is configured, not what the GROMACS code can do.
>>>>>
>>>>> Mark
>>>>>
>>>>> On Tue, Mar 21, 2017 at 4:44 PM Vedran Miletić <vedran at miletic.net>
>>>>> wrote:
>>>>>
>>>>> On 03/21/2017 04:09 PM, Erik Lindahl wrote:
>>>>> > Hi Vedran,
>>>>> >
>>>>> > We're already planning a wordpress move, mostly because that will
>>>>> make
>>>>> > it easier to integrate with discourse and a bunch of other stuff we
>>>>> > might (or might not) use.
>>>>> >
>>>>> > However, we have a couple of early-april deadlines, so it won't
>>>>> happen
>>>>> > until mid-april. Worst-case, I'm sure Stefan can make the site
>>>>> read-only
>>>>> > for two weeks :-)
>>>>> >
>>>>> > Cheers,
>>>>> >
>>>>> > Erik
>>>>> >
>>>>>
>>>>> Good choice. Discourse is also cool. Looking forward to the new
>>>>> website.
>>>>>
>>>>> Regards,
>>>>> Vedran
>>>>>
>>>>> --
>>>>> Vedran Miletić
>>>>> vedran.miletic.net
>>>>> --
>>>>> Gromacs Developers mailing list
>>>>>
>>>>> * Please search the archive at http://www.gromacs.org/Support
>>>>> /Mailing_Lists/GMX-developers_List before posting!
>>>>>
>>>>> * Can't post? Read http://www.gromacs.org/Support/Mailing_Lists
>>>>>
>>>>> * For (un)subscribe requests visit
>>>>> https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx
>>>>> -developers or send a mail to gmx-developers-request at gromacs.org.
>>>>>
>>>>>
>>>>> --
>>>>> Gromacs Developers mailing list
>>>>>
>>>>> * Please search the archive at http://www.gromacs.org/Support
>>>>> /Mailing_Lists/GMX-developers_List before posting!
>>>>>
>>>>> * Can't post? Read http://www.gromacs.org/Support/Mailing_Lists
>>>>>
>>>>> * For (un)subscribe requests visit
>>>>> https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx
>>>>> -developers or send a mail to gmx-developers-request at gromacs.org.
>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> --
>>>>> Erik Lindahl <erik.lindahl at gmail.com>
>>>>> Professor of Biophysics, Dept. Biochemistry & Biophysics, Stockholm
>>>>> University
>>>>> Science for Life Laboratory, Box 1031, 17121 Solna, Sweden
>>>>>
>>>>> --
>>>>> Gromacs Developers mailing list
>>>>>
>>>>> * Please search the archive at http://www.gromacs.org/Support
>>>>> /Mailing_Lists/GMX-developers_List before posting!
>>>>>
>>>>> * Can't post? Read http://www.gromacs.org/Support/Mailing_Lists
>>>>>
>>>>> * For (un)subscribe requests visit
>>>>> https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx
>>>>> -developers or send a mail to gmx-developers-request at gromacs.org.
>>>>>
>>>>>
>>>>> --
>>>>> Gromacs Developers mailing list
>>>>>
>>>>> * Please search the archive at http://www.gromacs.org/Support
>>>>> /Mailing_Lists/GMX-developers_List before posting!
>>>>>
>>>>> * Can't post? Read http://www.gromacs.org/Support/Mailing_Lists
>>>>>
>>>>> * For (un)subscribe requests visit
>>>>> https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx
>>>>> -developers or send a mail to gmx-developers-request at gromacs.org.
>>>>
>>>>
>>>> --
>>>> Gromacs Developers mailing list
>>>>
>>>> * Please search the archive at http://www.gromacs.org/Support
>>>> /Mailing_Lists/GMX-developers_List before posting!
>>>>
>>>> * Can't post? Read http://www.gromacs.org/Support/Mailing_Lists
>>>>
>>>> * For (un)subscribe requests visit
>>>> https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx-developers
>>>> or send a mail to gmx-developers-request at gromacs.org.
>>>>
>>>
>>>
>>
>> --
>> Gromacs Developers mailing list
>>
>> * Please search the archive at http://www.gromacs.org/Support
>> /Mailing_Lists/GMX-developers_List before posting!
>>
>> * Can't post? Read http://www.gromacs.org/Support/Mailing_Lists
>>
>> * For (un)subscribe requests visit
>> https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx-developers
>> or send a mail to gmx-developers-request at gromacs.org.
>>
>
>
>
> --
> --
> Erik Lindahl <erik.lindahl at gmail.com>
> Professor of Biophysics, Dept. Biochemistry & Biophysics, Stockholm
> University
> Science for Life Laboratory, Box 1031, 17121 Solna, Sweden
>
> --
> Gromacs Developers mailing list
>
> * Please search the archive at http://www.gromacs.org/
> Support/Mailing_Lists/GMX-developers_List before posting!
>
> * Can't post? Read http://www.gromacs.org/Support/Mailing_Lists
>
> * For (un)subscribe requests visit
> https://maillist.sys.kth.se/mailman/listinfo/gromacs.org_gmx-developers
> or send a mail to gmx-developers-request at gromacs.org.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://maillist.sys.kth.se/pipermail/gromacs.org_gmx-developers/attachments/20170919/38473971/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image.png
Type: image/png
Size: 368591 bytes
Desc: not available
URL: <http://maillist.sys.kth.se/pipermail/gromacs.org_gmx-developers/attachments/20170919/38473971/attachment-0001.png>