grburgess / ronswanson

Ron Swanson builds tables for 3ML
http://jmichaelburgess.com/ronswanson/index.html
Other
4 stars 2 forks source link

Docs: separate the intro and make a clearer case for ronswanson #7

Closed cosimoNigro closed 1 year ago

cosimoNigro commented 1 year ago

This issue is related to ronswanson's review for the journal of the open source software, specifically to the item:

A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?

Now in the docs there is a single Intro page with a brief statement of need, installation instructions and a first example. On the other hand, in the main doc page there is a brief introductory paragraph just stating:

This tool provides an easy interface to construct 3ML table models from computational expensive simulations on HPC systems. Why? Because it is your right to do so!

Though a conversational approach is always welcome in documentations, maybe the authors can better detail here the problem the software aims to solve, add some physical applications (what is the case of a simulation / analysis for which ronswanson would be useful?) and also for whom this software is helpful?

Maybe it would be better to have the installation instructions separated from the first example. They can go in the main page as well.

grburgess commented 1 year ago

@cosimoNigro This is a good point. I will clean up the docs and describe the problem more technically. I think I will also link in the docs from astromodels for further reading on the technical details of the template models as ronswanson is more focused on the the construction of the base data.

cosimoNigro commented 1 year ago

@grburgess, did you have time to improve the docs? That is to separate the installation from the tutorials and to better clarify the scope and applications of the package?

grburgess commented 1 year ago

@cosimoNigro I have implemented these changes now.

cosimoNigro commented 1 year ago

Installation instructions have been separated from the example and the latter is much more clear. Thanks.