JOSS review: suggestions on the example

lheagy commented 3 years ago

For the JOSS review (openjournals/joss-reviews#3344), I am working through the example, and as I work through, I will list a few questions / suggestions here:

rather than assuming that the build directory is in the home directory, it would be more convenient to always have relative paths (e.g. going back up / down from wherever you are currently)
for the testing step that uses the config file in the Wrap the model with the babelizer stage (last step): I would suggest you walk the user through creating that file from the command line (e.g. echo "1.5, 8.0, 6, 5" > config.txt) possibly in addition to providing the link to the config file that you can download. It wasn't obvious that the text in the docs was hyperlinked, and it is a bit of messing around to get the config file into the right directory for such a simple file
the directory structure gets a little involved, so it would be helpful to have a high-level summary / picture at the top to give an idea of where we are headed and the role of each directory. e.g. something like the image below is all I have in mind, and possibly with a couple of annotations of what each is

but all ran smoothly and the instructions are clear! Nice example :)

mdpiper commented 3 years ago

Hi @lheagy! Thank you for your careful reading and evaluation of the example. I'll implement all your suggestions. PR forthcoming soon-ish.

mdpiper commented 3 years ago

@lheagy Please let me know if #54 addresses your suggestions above. The docs build for the example is up at https://babelizer.readthedocs.io/en/mdpiper-fix-51/example.html.

csdms / babelizer

JOSS review: suggestions on the example #51