JOSS Review - Examples

[MaximevdHeijden]

Dear authors,

There are several issues with the examples, related to the documentation, including:

1. The documentation is long and not well organized (examples on different pages or incorporated in other pages (for example in the basic usage page)) which is not user friendly.
2. It is not clear which datafiles the user can use. It is mentioned that the software can be used for multiple commonly used battery testers but I cannot use the code with my Biologic (.mpr) data. Also, it is unclear what should be in the datafile and how the software reads the data.
3. Most of the examples don't refer to an Jupyter notebook with an example and the input data that can be used to test/understand the software.

Thus, the examples provided can be clarified and polished, especially because there are multiple locations with examples, all with their own problems: - Examples and tutorials/Basic usage Point 7 - Trying out: Please carefully check the documentation as it is not fully correct which is confusing for the user (for example, the following four errors occurred when trying the script: “KeyError: 'capacity'”, “KeyError: 'v'”, "Error: ModuleNotFoundError: No module named 'hvplot'", and Error: "FileNotFoundError: [Errno 2] No such file or directory: 'mdb-export'" as the parameter names were not correct and 'hvplot' and 'mdbtools' should be added to the dependencies). In this long page, there is a section on running your first script which is referring to examples. However, this is after the first example and it would be much better if this is a separate page. - Examples and tutorials/Example notebooks This section is a bit more clear as there are actual example notebooks. It would be nice if the notebook of interest is mentioned together with the input data so the user can very quickly check the notebooks. More notebooks should be added, at least add examples for all the types of data collection, analysis, and visualization options possible with cellpy, and how to use cellpy for different input datafiles (for different battery testers). - Examples and tutorials/Examples: This section is not finished and can probably be deleted.

To make the examples more user friendly and to increase the impact of the software, I suggest the following changes to the documentation:

1. Remove the examples from the basic usage page and split them into smaller pages related to their topic/example.
2. Add a clear example documentation per type of example with a link to the correct example script (jupyter notebook) with the correct example input data (.res file) to test the scripts.
3. In the example documentation, make a section dedicated to the datafiles that can be used for different battery testers so that the user knows how to use the software for their data.

This issue is related to https://github.com/openjournals/joss-reviews/issues/6236

[jepegit]

Dear @MaximevdHeijden, Thanks for the valuable suggestions. We will start working on improving the examples and documentation now. Will also will try to make the installation process a bit simpler. I guess we will need a week or so (because of lot of other things happening at work at the moment).

[jepegit]

Summary of tasks:

• [x] Remove the examples from the basic usage page and split them into smaller pages related to their topic/example.

• [x] Add a clear example documentation per type of example with a link to the correct example script (jupyter notebook) with the correct example input data (.res file) to test the scripts.

• [ ] In the example documentation, make a section dedicated to the datafiles that can be used for different battery testers so that the user knows how to use the software for their data.