search

FZJ-IEK3-VSA / FINE

The FINE python package provides a framework for modeling, optimizing and assessing energy systems
https://vsa-fine.readthedocs.io
Other
68 stars 39 forks source link

[JOSS] Documentation - Example usage #49

Open GregorBecker opened 6 months ago

GregorBecker commented 6 months ago

Hi, I have a question about the examples/tutorial section in JOSS Review 6274.

I've found the "Tutorial" section in your documentation where you only tell the modeling tool user that the examples are located in the "examples" folder.

In my opinion, it would be useful to present a brief description of each example (as found in the example notebooks) and link to them individually. This should include an introductory text and a logical order in which to use the examples to help the user learn how to use your software product.

I would also like to point out two formal things. First, you specify units in square brackets. Although this is common practice, it is not formally correct. Furthermore, it is not allowed to append indices to SI units. It would be nice if you could adapt this in your examples.

Nevertheless, I would like to emphasize that the description of the examples in the documentation is of greater importance.

Kind regards @GregorBecker

t-gross commented 5 months ago

Thank you for question and comments. In develop branch, we added short descriptions and the links to the individual examples. The examples were ordered. The descriptions and links to the examples were added in ReadTheDocs (Tutorial) and in the README file (both currently only available in develop branch). We will also work on the unit issue (thanks for raising it!).