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.

Copy part1.do.txt to slides-ch2/part1.do.txt.
Make slides_ch2.do.txt and include slides-ch2/part1.do.txt.
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.
Each part in the slide file has a DocOnce section heading with 7 =, while each slide has a DocOnce subsection heading with 5 =.
Edit slides-ch2/part1.do.txt:

One can keep subsection headings from the running text for the most part, but slides need many more subsection headings.
Try to let the heading summarize explicitly a conclusion/rule from the slide (the slide table of contents is then a set of conclusions/rules!)
Remember a !split right above every slide heading!
Compile frequently and look at the slides: they become over-full very quickly so there is a constant need for dividing slides into new ones with new headings.
Read a paragraph, focus on its main idea and result, and see how it can be condensed to one sentence or a few bullet points. Making effective slides is the art of condensing the most important information in the text to a eye-catching format.
Do not remove figures without a very good reason. Figures are important!
Add new images to liven up the presentation. In slides you may think of cartoons or entertaining images that would never be suitable in a chapter/book, but they may help attract attention, communicate ideas, and enhance the memory process.
Condense every mathematical derivation. Make sure the goal and end result is clear before diving into details.
Detailed derivations are seldom of interest in a study guide or oral presentation - refer to the underlying running text in the chapter for the details. Focus on ideas and key mathematical steps (if they are important enough).
Remember that equations are sometimes excellent images for ideas! Complicated equations can therefore be important slide elements although the details will never be addressed.
It is quite often wise to remove equation numbers in slides. You can automatically remove them by --denumber_all_equations, or you can edit the LaTeX math environment manually. Remember that references to equations numbers must be removed from the slides too!
Movies are effective in slides. It is still a hassle to get them displayed correctly in PDF files, so using a test on FORMAT and writing MOVIE for HTML output and just a link in PDF output might be necessary. See the manual for how to work with movies in DocOnce.

The slides are to fulfill three purposes:

reading as a study guide to get overview before reading the full text of chapter,
watching as slides during an oral presentation,
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:

First a plain LaTeX PDF document to catch as many errors in the DocOnce source as early as possible. This document can also be used for compact printing of the contents of the study guide (and the output looks definitely like a study guide and not slides!).
HTML5 reveal.js slides with different colors.
HTML5 deck.js slides. This format is usually inferior to reveal.js, but is also very much personal taste.
LaTeX Beamer slides. Edit the theme=red_shadow line in make_slides.sh to control the Beamer theme.
Remark (Markdown) slides for viewing in a browser.

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:

you simply get too much text in a too long notebook,
the notebook needs more code snippets than what you want to show in a book (or you just want to show fragments while the notebook requires complete code),
there are many cross-references between equations, sections, figures, and running text that the notebook does not support well.

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.