Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

D2.14: Demonstrators: Interactive textbooks: Problems in Physics with Sage and Computational Mathematics for Engineering #39

Open
minrk opened this issue Sep 8, 2015 · 40 comments

Comments

@minrk
Copy link
Contributor

@minrk minrk commented Sep 8, 2015

Interactive tools have always been an attractive tool in education, engaging the student to learn both by theory and by practice, to immediately test their understanding, and to explore around the material, all at their own pace.

In Task T2.9, we explored different approaches to authoring and distributing interactive textbooks using the Jupyter toolkit. In D2.9 (#49) we reported on the writing of two interactive books. There, the books were authored as structured text files in the ReST document format, and exported as interactive html pages or pdf, using the Sphinx documentation system and the sage-cell interactive html page technology.

For this deliverable, we proceeded with two additional interactive textbooks:

There we explored an alternative approach: the books were authored as collections of Jupyter notebooks, and exported as notebooks, html or pdf.

In this report, we set the stage by describing the benefits of (Jupyter-based) interactive textbooks from the learners and authors perspective, and review our two new interactive text books; we then discuss the workflows we explored, their relative merits, and some best practices to enhance quality and maintenability. We present a template abstracted away from our books that enables new authors to kick-start the writing of their own book. We conclude by highlighting the ease of distribution of interactive textbooks thanks to the Binder Virtual Environment. The table of contents of the two books is provided in the appendix.

Altogether, this demonstrates that the OpenDreamKit efforts, notably T4.1 (#69), T4.3 (#71), T4.6 (#74), and T4.8 (#76) contributed to lower barriers for including computations in science education while significantly improving the maintainability of such interactive materials by proper use of automated validation.

@minrk minrk added this to the D2.14 milestone Sep 8, 2015
@nthiery nthiery assigned marcinofulus and unassigned VivianePons Mar 22, 2016
@bpilorget bpilorget modified the milestones: Month 47: 2019-07-31, Month 48: 2019-08-31 Jan 11, 2018
@IzabelaFaguet

This comment has been minimized.

Copy link
Contributor

@IzabelaFaguet IzabelaFaguet commented Apr 16, 2019

Hello everyone!
We are organising an ODK report writing sprint From August 24th to August 31st,
a good opportunity to finish the final reports in a pleasant and friendly environment.
Would someone like to participate?

The link to the poll: https://framadate.org/tfuHjZgcSU8pHI45

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 25, 2019

I have read through the current file, made some minor editions and added some TODO's. Thanks much @fangohr and @marijanbeg for your more than timely contribution!

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 25, 2019

Hi @marcinofulus,
We urgently need your contribution: description of your textbook and elements of discussion based on your experience, so that the report can then be made into a single coherent whole.
What's your time line?
Thanks in advance,

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 25, 2019

Salut @ocayrol,
When this report will be roughly complete, it would be very useful if you could review it, and contribute to the discussion about tools, approaches, and best practices for authoring notebooks.
Would you have some time during the upcoming week? If yes, when?
Of course you are more than welcome to join here in Cernay :-)
Amitiés,

@nthiery nthiery changed the title D2.14: Demonstrators: Problems in Physics with Sage, Computational Mathematics for Engineering D2.14: Demonstrators: Interactive textbooks *Problems in Physics with Sage* and *Computational Mathematics for Engineering* Aug 25, 2019
@nthiery nthiery changed the title D2.14: Demonstrators: Interactive textbooks *Problems in Physics with Sage* and *Computational Mathematics for Engineering* D2.14: Demonstrators: Interactive textbooks: Problems in Physics with Sage and Computational Mathematics for Engineering Aug 25, 2019
@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 26, 2019

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 26, 2019

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 26, 2019

Bringing here a piece of conversation from D2.9 #49:

We should have add "interactive books" to our online use cases section, with references to all the interactive textbooks that we authored (and possibly others too). This would be a natural place to disseminate the discussions from this report: merits of interactive textbooks, available tools, best practices, etc.

There are two options to achieve this:

  • link from the use case page to the report;
  • move the discussions from the report to the use case page, and link to them from the report (or include a copy as appendix).

It feels like the latter will make the information easier to discover for potential authors, and have some more chance to keep evolving later on (e.g. addition of more references? of an authoring tutorial? of a cookie-cutter?.

What do you think?

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 27, 2019

I am preparing a cookie-cutter with all problems and solution in book-book workflow

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 29, 2019

Good morning @marcinofulus
I am reviewing the current version (@fangohr did some review earlier today).
In the mean time, could you write an abstract in the issue description above?
Thanks!

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 29, 2019

The abstract from D2.9 #49 is presumably a good starting point.

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 29, 2019

I worked on cookie cutter now, and I will also write a short subsection on it.

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 30, 2019

@marcinofulus: please also take care of the TODO's in the issue description above (abstract, ...).

Ops - I just overlapped my push with your comments 29min ago. -

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 30, 2019

No problem; this is bound to happen when 20 people are banging hard together:-)
I gather that you did or will handle the conflict, and handle the remaining TODO's?

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 30, 2019

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 30, 2019

yes - usually in sagecells I tries to aviod dependences, notebooks on the contrary are considered generally to be a one program (by me I mean)

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 30, 2019

Did you review 3rd perspective ?

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 30, 2019

@nthiery I am handling todos now...

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 30, 2019

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 30, 2019

@nthiery was sagemath/sagemath:latest docker image done by ODK?

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 30, 2019

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 30, 2019

I have updated https://github.com/OpenDreamKit/authoring_cookie_cutter, mentioned in - it implements workflow without notebook output cells in git (also no nbval).

@nthiery nthiery removed the needs review label Aug 30, 2019
@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 31, 2019

I have just reviewed the document, extracting an abstract in the github issue above. Altogether, it's very close to be ready.

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 31, 2019

@ocayrol: please see if you could contribute some of your insight on the Sphinx vs Notebook authoring workflows:

\subsubsection{Workflows and comparison of their relative merits}

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 31, 2019

@marcinofulus: there are still a few questions from the original task that are not addressed in our report; see the github issue description above. Can you see what can be done?

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 31, 2019

@IzabelaFaguet: please proofreading the whole text.

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 31, 2019

@marcinofulus: there are still a few questions from the original task that are not addressed in our report; see the github issue description above. Can you see what can be done?

I think that they are answered indirectly, but of course I will try to make it more direc.

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 31, 2019

I added some direct answers to monograph questiom I think also that there is already answer on collaboration (github vs email to github operator;).

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 31, 2019

@nthiery , I think that now questions are addressed.

@embray

This comment has been minimized.

Copy link
Collaborator

@embray embray commented Aug 31, 2019

I made a few minor proofreading edits.

@marcinofulus

This comment has been minimized.

Copy link
Contributor

@marcinofulus marcinofulus commented Aug 31, 2019

@embray thanks!,

@nthiery nthiery removed the in writing label Aug 31, 2019
@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 31, 2019

Thanks @marcinofulus for the last touches.
@embray: really appreciate all the continuous proofreading you have done; it's super precious and got this deliverable on time!

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 31, 2019

Well, almost; for some reason, it was due M47. Good enough :-)

@nthiery nthiery added the Submitted label Aug 31, 2019
@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Aug 31, 2019

Good that I checked a last time my e-mail in my tent before going to sleep :-)

@marcinofulus, @fangohr: thanks for the report which will be a useful read for future authors too.

Four textbooks that is, while exploring and demonstrating ODK technologies; pretty cool! Thanks a lot for all the work; @marcinofulus: you'll congratulate all contributors in Silesia on my behalf. With a thought for Jan.

I am looking forward a use case section on interactive text books!

@nthiery

This comment has been minimized.

Copy link
Contributor

@nthiery nthiery commented Sep 2, 2019

The use case section should mention jupyter-book as well (book authored in notebooks + markdown; export as static web site with Jekyll, with download links, in the work ThebeLab support, etc.). Originates from the Data 8 course.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.