LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Mailing List Archives
Re: [lammps-users] lammps-users Digest, Vol 143, Issue 53
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [lammps-users] lammps-users Digest, Vol 143, Issue 53

From: Giacomo Fiorin <giacomo.fiorin@...24...>
Date: Fri, 13 Apr 2018 15:10:54 -0400

On Fri, Apr 13, 2018 at 2:27 PM, Moore, Stan <stamoor@...3...> wrote:
I definitely agree the LAMMPS doc pages could be improved. There is a lot of redundant info and info buried down deep in there. But I would also say that the LAMMPS documentation is far better than most research codes :)

Second that.

In codes that are less complex than LAMMPS (which I'm familiar with, thus throwing my two cents) the difficulty to find out "how to do X" is also a problem.

But pages like this:
are quite useful, yet users of many other codes don't have them.

Unfortunately a reference manual will never be useful to *everyone*, as it will be read by very few.  Axel already pointed out in good detail the changes in the user community.

Given that, the most useful critique of the documentation can come from those who spent a lot of time reading it.



-----Original Message-----
From: Axel Kohlmeyer [mailto:akohlmey@...24...]
Sent: Friday, April 13, 2018 7:40 AM
To: Steve Plimpton <sjplimp@...24...>
Cc: Noam Bernstein <noam.bernstein@...4479...>; lammps-users <>
Subject: [EXTERNAL] Re: [lammps-users] lammps-users Digest, Vol 143, Issue 53

On Fri, Apr 13, 2018 at 9:13 AM, Steve Plimpton <sjplimp@...24...> wrote:
>>> The problem is that I find the many aspects of the organization of
>>> the documentation unintuitive, so I wasn’t able to find that through
>>> the searching I did.
> I think Noam's comment is on-point.  The LAMMPS doc pages and website
> info have grown organically over the years, and are now vast and
> complicated.  It is often hard to find the answer you're looking for,
> even for a power-user like Noam.


i am not disagreeing with the fact, that the documentation can be improved; that it is vast and extremely and needlessly repetitive and unfocused. in fact, you should recall, that i have repeatedly made proposals for how i think this should be changed and the overall structure improved. and that is exactly the point of *my* criticism
here: saying that something is not good is meaningless without pointing out why and where.

> It's something we should try to simplify if we can find time to do it.

that is the second point i am making (and have been making over and over again for years). documentation is something where non-developers can support the community and, both, help themselves and others by contributing improvements. at the current pace of development and availability of time of the core developers, i don't see much of a chance for any of that to happen soon (or later). that is why i am calling out people to not just say that something needs to be improved, but am asking them to make an active effort. we have a large enough user base. if only half of them makes a small contribution, that will take us already very far. ...and one does not really need to be an expert for this:

when i was in grad school, my department head would always say "you want to enter a new field of research, start by writing a review". for a long time, it didn't make much sense to me to have a beginner (and not an expert) do a review. but i have since understood why, and for software i found that this statement can be modified to "if you want to understand a software, write a tutorial" or "... rewrite the documentation". so the common excuse "i cannot write documentation because i am not an expert", does not hold: a) because experts do not understand the perspective of a beginner well, so it is difficult to write a documentation for a beginner (or intermediate or non-developer), b) writing (good!) documentation forces you to understand how something works (same as for the review writing case), so it is an opportunity to teach yourself valuable knowledge and skills, even if you never aim to become a programmer.
over many year i myself have contributed tutorials to multiple software packages, some of which are still available, and often near the beginning of my involvement with a project, and then later some of these tutorials actually ended up to become contributions to the respective codes or their documentation.


> Steve
> On Fri, Apr 13, 2018 at 6:22 AM, Axel Kohlmeyer <akohlmey@...24...> wrote:
>> On Fri, Apr 13, 2018 at 7:53 AM, Giacomo Fiorin
>> <giacomo.fiorin@...43...4...> wrote:
>> > From the doc:
>> >
>> > Typing “make package-update” or “make pu” will overwrite src files
>> > with files from the package sub-directories if the package is
>> > installed. It should be used after a patch has been applied, since
>> > patches only update the files in the package sub-directory, but not
>> > the src files.
>> >
>> > Is there perhaps a language barrier issue?
>> i would say that this is more of a "cultural" issue.
>> the LAMMPS manual is *vast* (>2000 pages) and for a very long time
>> and particularly in the beginning, the only way to obtain LAMMPS was
>> via downloading a tar archive or patch files from
>> a lot of the wording historically assumes that you obtain LAMMPS from
>> tar archives and patches and not subversion or git. some of the
>> LAMMPS core developers feel that this is the still the most common
>> way and we have no way of knowing whether this is the case or not.
>> also, the LAMMPS user base initially was much more that of people
>> doing development and less that of "i just want to use it" people.
>> thus there are parts in the documentation that make assumptions of
>> its readers that may not be as true as they used to be. it is
>> difficult for current developers to spot these (because for them
>> these are obvious things). it is best revised by people that are not
>> developers, as they know the perspective of a non-developer *much* better.
>> axel.
>> p.s.: noam, please fix your email or subscribe from a different
>> account. all replies to your address get rejected with messages like
>> this (which is hugely annoying):
>> ** Message not delivered **
>> There was a problem delivering your message to
>> noam.bernstein@...6163...9.... See the technical details below, or try
>> resending in a few minutes.
>> The response from the remote server was:
>> 554 5.7.1 Action Returned message to Sender:<akohlmey@...24...>,
>> Subject:Re: [lammps-users] lammps-users Digest, Vol 143, Issue 53,
>> Messages Rejected, Notify Recipient
>> --
>> Dr. Axel Kohlmeyer  akohlmey@...24... College of
>> Science & Technology, Temple University, Philadelphia PA, USA
>> International Centre for Theoretical Physics, Trieste. Italy.
>> ---------------------------------------------------------------------
>> --------- Check out the vibrant tech community on one of the world's
>> most engaging tech sites,!
>> _______________________________________________
>> lammps-users mailing list

Dr. Axel Kohlmeyer  akohlmey@...43...4... College of Science & Technology, Temple University, Philadelphia PA, USA International Centre for Theoretical Physics, Trieste. Italy.

Check out the vibrant tech community on one of the world's most engaging tech sites,! _______________________________________________
lammps-users mailing list
Check out the vibrant tech community on one of the world's most
engaging tech sites,!
lammps-users mailing list

Giacomo Fiorin
Associate Professor of Research, Temple University, Philadelphia, PA
Contractor, National Institutes of Health, Bethesda, MD