Review JOSE submission - General comments

[jwagemann]

• adjust title to e.g. ClimateEstimate.net - Weather Panel is misleading
• have a native speaker and someone external read through the tutorial text - sometimes the sentences are a bit cryptic and hard to follow
• Make use of coloured boxes to introduce content such as ‘Nice to know’ , ‘Note’ or ‘Hint’
• since it is a Jupyterbook - it would be actually very nice to have the examples in for of Jupyter notebooks available where learners can try out the examples while following the tutorial
• add to each section an ‘Additional resources’ section and add there in bullet points all additional external content you are referring to
• headings are often quite mis-leading, e.g. when you introduce shapefiles, the header of the section is called ‘geographical information systems’
• from the beginning till the end, it is not clear to me what each section aims to achieve. Examples are not easy to follow and I don’t believe that anyone apart from the authors could pick up the tutorial and can teach with it. Make yourself clear, what aim each section has and only add content that helps to meet the aim of the section

[jrising]

Thank you for all of the comments here and in the preceding issues! Here are our responses to these points.

adjust title to e.g. ClimateEstimate.net - Weather Panel is misleading

Now fixed. The main title, welcome page and tutorial logo have been changed.

have a native speaker and someone external read through the tutorial text - sometimes the sentences are a bit cryptic and hard to follow

This is potentially always something to improve. We've now edited all of the sections and fixed a number of typos, and shared the tutorial with more native speakers.

Make use of coloured boxes to introduce content such as 'Nice to know', 'Note' or 'Hint'

Thank you very much for pointing out this option! We’ve upgraded to a newer version of Jupyter Book, which allowed us to use these colored boxes (and other features) and overall make this tutorial much nicer.

since it is a Jupyterbook - it would be actually very nice to have the examples in for of Jupyter notebooks available where learners can try out the examples while following the tutorial

We've added a common Hands-On Exercise throughout the tutorial. These examples remain in Markdown, as we'd like to provide examples in multiple programming languages. We have also tested an interface between our Jupyter Book site and Binder to allow online execution (PR #46), but have not settled on a particular use case.

add to each section an 'Additional resources' section and add there in bullet points all additional external content you are referring to

Instead of placing these resources at a single place, we decided to add them throughout the text (where a reader can immediately check them out) as hyperlinks or colored “see also” boxes.

headings are often quite mis-leading, e.g. when you introduce shapefiles, the header of the section is called 'geographical information systems'

A number of the headings have now been changed. We have kept the "Geographical information systems" header, but mostly discuss the GIS concepts in general. We have also added a lot more subheadings and broken content up more, so that each section has a more concrete purpose.

from the beginning till the end, it is not clear to me what each section aims to achieve. Examples are not easy to follow and I don't believe that anyone apart from the authors could pick up the tutorial and can teach with it. Make yourself clear, what aim each section has and only add content that helps to meet the aim of the section

Each section now starts with a "Key objectives and decision points" box. We hope that this will both let readers identify the sections they need more easily, and connect our structure back to the "decision points" vision that we have for the tutorial as a whole.