[JOSS review] Suggestions for user manual

mstimberg commented 4 years ago

Issue opened as part of the JOSS review (openjournals/joss-reviews#2331)

Here are a few issues I noticed in the user manual:

The user manual does not seem to mention the parameter fitting functionality
It seems that the command-line interface has less functionality than the GUI. This should be clearly stated in the user manual and elsewhere (e.g. the github README currently states: "It provides graphical user interface on top of command-line interface")
3.4.7 (p.11): "accepts a formula (in an infix notation)" – this is a bit odd, would a user expect e.g. postfix notation? Also, formula here just refers to an arithmetic expression, and not to arbitrary formulas (using exp, sqrt, ...) I imagine? If there is support for a power operation, does it use "^" or another symbol?
3.4.7. (p.11): The documentation talks about "value-sets" but it seems that in the application they are actually called "parameter sets". Also, the software asks whether to create a "parameter", "product", or "zip" after selecting "Define parameter set" – the documentation only talks about the "parameter" functionality, as far as I can see.
The installation creates additional command-line binaries (flint-cli, flint-run, flint-tr, ...), but these are not mentioned in the user manual and only have very brief README files. Are these only meant for internal use?

Minor issues/typos:

1.1 (p.3): "...via an external program such as gnuplot" – I think gnuplot is the only program that is directly supported?
2.2 (p.5): broken link to Figure
3.4.1 (p.9): "simulatoin" → "simulation"
3.4.6 (p.10): "matching its properties, such as name" – what other properties can be matched? Is using a pattern the only way to specify the outputs, or can you also select them directly in the GUI?
3.6.2 (p.13): "these operation" → "this operation"
3.10.2 (p.15): at least on Linux, it does not seem to be necessary to specify the path to gnuplot

tabe commented 4 years ago

Updated the user guide by addressing your points. You can download its pre-release version at https://flintproject.github.io/doc/flint-2.4.0-user-guide.pdf.

mstimberg commented 4 years ago

I think all my comments have been addressed, I'm very happy with the changes.

flintproject / Flint