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

Szilárd Páll pall.szilard at gmail.com
Mon Sep 18 15:26:07 CEST 2017 

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

More information about the gromacs.org_gmx-developers mailing list