JOSS review: documentation

[ranocha]

• I am not familier with Vlasiator. Thus, it would be nice for someone like me to include a basic tutorial how to obtain such simulation data (or at least link to a Vlasiator tutorial).
• It would be great to get a basic introduction to the package already in the README.md, e.g., basic installation instructions and a simple use case.
• It may be confusing that the URLs in the "About" section on GitHub and in the README.md point to the development documentation, not the latest stable release (which people will usually install).
• It would be nice to add a link from the documentation to the repository (to make it easier for people to see the code when they find the documentation with a search engine). For example, the first sentence on https://henry2004y.github.io/Vlasiator.jl/stable could start with "Vlasiator.jl is a data processing and analyzing tool" instead of "Data processing and analyzing tool".
• The gallery at https://henry2004y.github.io/Vlasiator.jl/stable/gallery/ is nice - but it lacks links to the source code used to generate the plots.

Xref openjournals/joss-reviews#4906

[henry2004y]

Thanks for the review! I have one question regarding links to the plotting source codes: the data for generating some of the good-looking plots are either private or too large to put on a public server. How should I handle that in general? Are links to sample plotting scripts without data enough @ranocha?

[ranocha]

Could you maybe provide some sample data you can use as a stub (also for testing)? You could have a high-resolution version in the gallery followed by a low-resolution version people can use to reproduce the visualizations.

[henry2004y]

Currently the test data can be obtained from vlsv_data, which is mentioned in the Log Section of the documentation. These files are also used for testing. For potential Vlasiator.jl users, it is highly likely that they will first obtain some pre-existing data from private servers and then perform analysis with Vlasiator.jl. Hopefully these reference VLSV output data are enough for checking the validity of the software --- they may be changed in the future if we want higher coverage rate or new features are requested.

[ranocha]

Sounds good to me. This issue can be closed once the software version in the paper is updated accordingly.