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: Axel Kohlmeyer <akohlmey@...24...>
Date: Fri, 13 Apr 2018 09:39:36 -0400

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@...24...> 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@...7547... 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@...24...
College of Science & Technology, Temple University, Philadelphia PA, USA
International Centre for Theoretical Physics, Trieste. Italy.