$$ \newcommand{\tp}{\thinspace .} $$

 

 

 

Study guides and slides

DocOnce has good support for creating slides. Especially if you have ordinary DocOnce documents with running text, it is an efficient process to strip down this text to a slide format.

Rather than speaking about slides, we think of study guides where the material is presented in a very condensed, effective, summarizing form for overview, use in lectures, and repetition. The slide format is a good way of writing study guides, but by explicitly thinking of study guides the slide format can be made more effective for self-study when overview and repetition are necessary - with a particular emphasis on gaining understanding.

Slides can easily be too crowded or too empty. It is a very challenging balance between enough information for self-study by reading slides and the modest amount of information you want in slides for oral presentations. For a talk, you will have (very) little text on slides and rely on figures. This is not so effective in a teaching and study guide setting. Some text is indeed necessary, but it has to be minimized. Michael Alley's evidence-assertion slide design is effective: summarize the slide's key point in a heading over 1-2 lines, use figures/equations/code effectively, and work on minimizing text.

Make it an assumption that the reader of a study guide is also a reader of the underlying running text in the chapter.

Slide directory

For each DoOnce file in the chapter ch2 it can be wise to make a corresponding study guide file in the subdirectory slides-ch2. For example, part1.do.txt has its counterpart with slides in slides-ch2/part1.do.txt. Then there is a file slides_ch2.do.txt which assembles the parts if slides-ch2, typically with a content like

TITLE: Study Guide: Some title
AUTHOR: Author Name Email:somename@someplace.net at Institute One
DATE: today

# #ifdef WITH_TOC
!split
TOC: on
# #endif

# #include "lec-ch2/part1.do.txt"

# #include "lec-ch2/part2.do.txt"

# #include "lec-ch2/part3.do.txt"

Generating slides from running text

The author has the following work flow for generating slides for a chapter file, say part1.do.txt.

  1. Copy part1.do.txt to slides-ch2/part1.do.txt.
  2. Make slides_ch2.do.txt and include slides-ch2/part1.do.txt.
  3. Decide on parts of the slide collection. Often a part can be a section in the parent ch2.do.txt file, but sometimes it can be more natural to have larger parts than sections in the slide collection.
  4. Each part in the slide file has a DocOnce section heading with 7 =, while each slide has a DocOnce subsection heading with 5 =.
  5. Edit slides-ch2/part1.do.txt:
The slides are to fulfill three purposes:
  1. reading as a study guide to get overview before reading the full text of chapter,
  2. watching as slides during an oral presentation,
  3. reading as a study guide to repeat and enforce overview of the material.
It is highly non-trivial to meet all these purposes: limit the information on the slides, make them as visual as feasible, make them self contained, and provide the sufficient amount of information. Considerable iterations are always needed. Reading the slides as a study guide is easy to accomplish. The slides' properties in live presentations can only be tested by speaking to them (making a rough draft of a video podcast is a very effective way of testing the slides' quality).

Tip: use quizzes to define a sufficient preparation level. You want students to study the slides/study guide before a lecture. To measure to what extent this is done, you can insert multiple-choice questions about the most basic concepts in the slides (using the DocOnce quiz environment). With quiztools you can extract all such multiple-choice questions, create online games with Kahoot, and let the students answer with their smart phones at the beginning of a lecture. The scores are visible to all on the main screen and communicate the preparation level.

Slides as IPython/Jupyter notebooks

I would add a fourth requirement to the list in the previous section: a study guide should also be available as an IPython/Jupyter notebook for experimentation, extension, and personal notes. This is technically straightforward by just generating a notebook from the slide source, but a notebook puts some constraints on code snippets and figures such that it is meaningful to execute all the code. Moreover, many figures are inlined and appear as a result of executing code in a notebook. While other formats will show a code snippet and then the corresponding figure, the notebook can leave the figure out and let it appear as the code cell is executed. Technically in DocOnce, this is solved by putting a FIGURE construction inside an # #if FORMAT test (or % if FORMAT if Mako branches are preferred). If `FORMAT != 'ipynb``, you have a FIGURE line, otherwise the preceding code cell is supposed to generate the figure.

Notebook from a chapter or from slides? The book's running text can also be converted to a notebook. However, the notebook then consists of very much text and often a lot of cross-referencing because this is the typically writing style of a book chapter. This style is not so effective for a notebook. Stripped text with focus on formulas, code, and figures is more ideal for a notebook and this is the style of a study guide realized by slides.

Compiling slides

There is a quite general script in doc/src/chapters/make_slides.sh for compiling a slide collection defined in a file like slides_ch2.do.txt. Just run

Terminal> bash ../make_slides.sh slides_ch2

from the chapter directory. Note that the script will first spell check the slide files. This is done in the slides-ch2 directory. Errors are reported in files located in slides-ch2. To update the chapter's dictionary for spell checking, you need to do

Terminal> cp slides-ch2/new_dictionary.txt~ .dict4spell

in the ch2 chapter directory.

Similarly, to look at misspellings, the file slides-ch2/misspellings.txt  is the relevant file.

The make_slides.sh script compiles a variety of slides:

IPython/Jupyter notebooks

Since DocOnce documents can be translated to IPython/Jupyter notebooks, hereafter just called notebooks, it is tempting to produce a version of the teaching material also in notebook form. This author's experience is that a more traditional book format with running text is not so ideal for a notebook:

Instead, making slides from the chapter's text and translating slides to the notebook format is a splendid idea. This requires some tuning, as you want slight differences between classic slides and a notebook. For example, a code snippet that results with a plot should contain the plot in classic slides, while the notebook will automatically produce it when run. This is easily fixed by an if test in Mako, typically % if FORMAT != 'ipynb': followed by a FIGURE: line that includes the resulting figure for all formats except the notebook.

Also be aware of the DocOnce hidden code environment that can be used to declare code blocks that appear in notebooks (because they are needed) but not in other formats: !bc pyhid gives a Python hidden snippet.

Using notebooks as a starting point for a traditional textbook might be a good idea, but will enforce a non-conventional style in the textbook. For example, notebooks should be quite small, leading to similarly small modules in the book. Notebooks use cross-referencing to little extent, and this will be reflected in the textbook too. Notebooks also need more code to run, so one has to accept more code in the textbook. However, there is still a problem for the notebook with defining items for an index, fancy admonitions, and other elements that one would desire in a textbook. More experience is needed to make best practices. Since notebooks can be compiled in Markdown, and DocOnce can read basic Markdown input, it is possible to go from the notebook format to DocOnce, but this is not tested.

Remark. More best practices for turning teaching material into books and into notebooks are supposed to be collected here in the future.