Hello!
High time to start a new “open discussion”.
If you have some thoughts about the LAMMPS documentation, please share them.
Specifically it would be nice if you would have comments on:
what is done well?
what is done badly?
what is missing?
what is too much?
where are errors (spelling, math expression don’t display correctly, bad URLs, incorrect URLs, missing URLs, outdated URLs, broken internal links)?
We have come a long way from where it was 4-5 years ago, but there is still a lot that can be done.
While we would like to have you share your thoughts, we would even more appreciate it, if you would be interested to help working on improving it yourself and submitting pull requests to the LAMMPS git repo. You don’t need to be a programmer to do that, and users are generally much better qualified to review, edit and improve documentation than developers (except perhaps for the developer notes ). So please also reply if you want to discuss how to get involved.
Great topic, I volunteer with the documentation. Personally, I find the major problem is the lack of homogeneity, as individual commands have been documented by different people. As a result, some commands are explained in a didactic way while others are very technical and dry.
Also, sometimes critical information is hidden in the text and does not stand out, making it hard to identify an error. For example, the fix npt/asphere uses the roto-translational temperature to compute the internal pressure. I believe the translational temperature should be used instead, but the commands to do so are only obvious to the experienced user. I would document this knowledge, to make life easier for the end-user (disclaimer: I have tested this behaviour with the MOLC model and Lammps version October 2019).
Another aspect of this is that some pages describe too many variants of commands so that it becomes hard to follow which part is relevant to which pair style, for example. While other pages are very brief and very similar to others, so they might be better combined into a single page.
Variable needs to be documented in its own chapter, since the incredible flexibility of variables is arguably a distinctive power of LAMMPS. (And as veterans of the mailing list know, with great power … comes great irresponsibility!)
The great long alphabetical list of fixes (commands, computes, etc) is also quite opaque. While it certainly has its uses, a more useful list would categorise fixes e.g. into integrators, force modifiers, etc.
At a minimum, it might be possible (and automateable) to categorise fixes by the packages that contain them. Fixes might also be automatically categorised by whether they contain a pre_force, post_force, or both methods (or in general where during a step they’re invoked). Computes might be automatically categorised by whether they output a scalar, fixed-length vector, or variable-length vector. Each of these might yield slightly alien categories but could potentially be automated in code somehow.
One thing that I’ve always been wondering about is whether people read the LAMMPS manual on e-books?
While most e-book readers, of course, support reading PDF files, it is also possible to build the manual in epub (and mobi format which is used by amazon’s kindle readers via conversion from epub) specifically for e-book readers.
These days it often seems as if people predominantly (if not exclusively) are reading the manual in the online version.
I enjoy browsing the PDF manual (which is also environmentally friendly), as I find it handy to have a clickable list of commands. One suggestion could be to implement a similar tree structure for the options of individual commands. Take a ubiquitous command such as fix npt: it has tons of options, and it’s cumbersome to spot a specific one by its formatting alone.
You are welcome. You are probably also a minority. I get the impression that - at least within people that post questions to the mailing list or forum - the online html documentation is what most people look at.
First you need to understand that the current layout and structure of the manual and specifically the documentation of individual command have historical reasons: Until about 2 1/2 years ago the documentation was only partially written in ReStructuredText, but mostly in a much simpler markup and then converted to .rst files with a converter tool and translated to html (or PDF) from there. That procedure was introduced about 3 years before that. At that time the PDF version of the manual was created from the html files with htmldoc (with next to no crosslinks). The original used “quoted text” sections as a simple way to have an alternate formatting to itemized lists. The bulk of the LAMMPS homepage is still created this way (which explains why it looks like it was frozen in time. In a way is is.).
I see three major challenges with your suggestion:
As far as I know, clickable links in the .rst files have to use unique keys. We already struggle with this when referencing citations (mostly because the citations are not supposed to be used the usual way where they all lead to a large bibliography section, but list them at the bottom of the individual pages documenting the commands) and have written scripts to check and show us where non-unique keys are. One way to get those would be to use sub-sub-sub-(sub-?)headings, but we already have too many nesting levels and making more visible would blow up all pages massively due to the navigation (which is replicated in each html page). This slows down loading the html pages and blows up the downloadable tarballs (not the git repo any more since the html files are no longer included in the repo). We have been there and adjusted the nesting. So some alternative way needs to be found.
Somebody needs to demonstrate what a formatting would be like that makes this more visible, readable (there is certainly room for improvement due to how it was conceived as described above), and clickable that also finds the support of all core LAMMPS developers (not always easy for people who spent 20+ years writing documentation in the simpler, previous markup). Opinions about what is practical and worth doing vary. A major concern is always the effort required and the complexity of the file format. Same as for the C++ source code, there is always a mandate to not only make it work efficiently, but also write it so that it is sufficiently easy for a self-educated “casual” programmer (i.e. most people doing computational research) to write and maintain it. We only deviate from this mandate when the benefits significantly outweigh the added complexity and when it concerns areas that are not so likely maintained by contributors to LAMMPS (e.g. the Programmer’s Guide section).
There needs to be sufficient workforce available that implements such changes, since I doubt there would be a way to automate this. Workforce is our biggest challenge. Given the size of the LAMMPS core team (and our advancing age!), there is significant concern about who will be maintaining LAMMPS in 10 years from today. Of course, a demonstration of a tool that is able to automate the necessary bulk conversion of rst file without introducing (many) errors or dropping content would be a major win.
Thanks for sharing the insider’s view of the problem. Since I need to document a new compute which I would like to submit with the next paper, I will experiment with different layouts. I may post the results here, so we can discuss together if that is something useful to introduce.
Yeah, restructuring the manual in this way is not easily accomplished with scripting, as it requires changing the main text and grouping all options in a definition list with internal links, or something like that. Maybe one day there will be a neural network able to do this task, who knows?
). So please also reply if you want to discuss how to get involved.