[JOSE] Pedagogy / Instructional design

[BenjMy]

xref openjournals/jose-reviews#185

The documentation design with respect to the learning objectives stated in the article can be improved.

I suggest the authors articulate the notebooks over sections and subsections. Ideally, I would distinguish within new section tutorials which are GemPy-dependent from the others. Also, you could articulate the notebooks using sections following your "Learning Objectives" workflow.

Note that individually each notebook is thoroughly documented to guide the user and it is really much appreciated!

[jwagemann]

• The organisation of the notebooks does not allow an easy understanding what notebooks belong to what unit as described in the paper
• There is a potential to organise the notebooks in a more intuitive way and also to give them a more meaningful nomenclature, instead of e.g. 'example32'
• In general, the notebooks can be made more educational
  • Most of the code is only sub-divided by headings, but most code is not explained what it actually does
  • In my opinion the notebooks do not meet the standard of a well-described, self-explanatory tutorial and need to be reworked in order to be pedagogically meaningful
  • Try to re-organise the content and link previous and next notebooks from within the notebook
  • An index page that provides an overview of notebooks and how they should be followed could be also a good idea
  • Consider also providing an overview of the notebook itself at the beginning of each notebook (with anchor links)
  • Some ideas on how to make notebooks more educational can be found here
• You address learners in third person (e.g. ‘in this tutorial the user learnt’) → I suggest to use a direct addressing - ‘you will learn …’
• Each notebooks has an empty code cell at the end —> this needs to be cleaned up

[AlexanderJuestel]

• The organization of the notebooks does not allow an easy understanding what notebooks belong to what unit as described in the paper --> This was addressed in introductory notebooks that users have to go through prior to the tutorials
• There is a potential to organise the notebooks in a more intuitive way and also to give them a more meaningful nomenclature, instead of e.g. 'example32' --> The notebooks were reordered into sections with better slightly better names
• In general, the notebooks can be made more educational --> The notebooks were made more educational by adding more theoretical aspects to the notebook
• Most of the code is only sub-divided by headings, but most code is not explained what it actually does --> Additional markdown was added to explain the code
• In my opinion the notebooks do not meet the standard of a well-described, self-explanatory tutorial and need to be reworked in order to be pedagogically meaningful --> The notebooks were reworked
• Try to re-organise the content and link previous and next notebooks from within the notebook --> Notebooks were linked
• An index page that provides an overview of notebooks and how they should be followed could be also a good idea --> Indices were added
• Consider also providing an overview of the notebook itself at the beginning of each notebook (with anchor links) --> Links to the different sections in notebooks were added
• Some ideas on how to make notebooks more educational can be found here
• You address learners in third person (e.g. ‘in this tutorial the user learnt’) → I suggest to use a direct addressing - ‘you will learn …’ --> That was partially addressed
• Each notebooks has an empty code cell at the end —> this needs to be cleaned up --> Notebooks were cleaned up

[AlexanderJuestel]

@jwagemann and @BenjMy, I have worked on your comments and would like to ask you to have a look at the reworked notebooks.