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

Mon Sep 18 17:07:14 CEST 2017

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.

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!)

So, wouldn't it make more sense to only have documentation for the actual
released versions, not separate it into patch levels?

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://maillist.sys.kth.se/pipermail/gromacs.org_gmx-developers/attachments/20170918/02400661/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/20170918/02400661/attachment-0001.png>