About lecture notes

A very popular feature of my classes, based on feedback on course evaluations, is that I provide lecture notes for my students. When I mention this to other instructors, there is often debate about whether this is good or not:

• Students won’t come to class! True, they are more likely to skip classes. On the other hand, I think the benefits for students, even for those who do come, outweigh the costs for students who don’t.
• Students won’t learn how to take notes! I’m not so sure that this is necessarily true.
• It takes a lot of time! It sure does! Luckily, that turns out not to be an issue for me.

So why do I do it? This actually has to do with that last point: I have to make notes for myself anyway.

I developed my “voice” through the ancient early-2000s art of “blogging”. This is a lot of work and I don’t do it for one-off presentations like conference talks. But for classes, where you are giving a series of lectures that depend on each other, I wanted to be more deliberate about planning and timing. So I write up what I plan to discuss and since I have all these notes written up anyway, I may as well put them up (of course, one has to make sure to add the disclaimer that these are not perfect).

Now, why do I think students benefit from this? The primary reason and the original motivation was for accessibility.

• Students who require things like note-taking accommodations have them readily available.
• Students who need to miss class for whatever reason have a record of what was covered in class. This has become much more important now that we’ve been forced online. Despite our best efforts, lecture capture is still not entirely foolproof—I’ve had a number of instances where the equipment was faulty and was not able to fix it before class. Written notes are a way to mitigate this deficiency.

Anyhow, I think everyone benefits from having class materials be made more accessible. In light of that, the how of producing lecture notes to be made available is a bit more involved.

How

It’s easy enough to type everything in $\LaTeX$ and throw a PDF up on the course website, but I put a bit more effort into this. The primary motivation for this was for myself: lecturing from a PDF in class is not convenient. Specifically, trying to read a PDF on a tablet is not great.

My solution was to use plain old HTML. There are two benefits:

• HTML is more accessible than PDF, so it’s a benefit from an accessibility perspective.
• HTML is more convenient to use on a table, so it’s a benefit for me.

All it takes is a bit of CSS and design sensibility (luckily, I’m a typography nerd) and you can have a document that looks sharp that works if all you need is text and images. However, since I teach theoretical computer science, I have a few additional needs.

Code

This is not too bad, as there are any number of JavaScript syntax highlighting libraries out there. I use Prism, since it has support for Python and what used to be our CS1 language of choice, Racket.

Math

Math was one of the first things I had to figure out. I use MathJax for a few reasons.

1. It’s the first tool I came across and tried.
2. It’s accessible for screen readers.
3. It has a very pedagogically valuable tool: anyone can right-click on a formula to have it display the underlying TeX commands.

Pseudocode

I use pseudocode.js. This renders pseudocode with TeX rather than attempting to mimic monospace-set code. In algorithms classes, I prefer approaching and teaching pseudocode as structured math and prose rather than less-stringent code.

Theorem numbering

This was something I used to do by hand and it sucked. However, I managed to finagle some CSS into doing my bidding. This is particularly useful as numbering may not line up from offering to offering. One hitch to this is that the Safari renderers don’t support certain settings so sectioning doesn’t quite work on iOS devices. This isn’t the end of the world, but I haven’t quite figured out a way to make this work satisfactorily. Update: The problem was the use of counter-set, which is not a standard CSS attribute. The correct usage is to use counter-reset.

The following CSS defines a bunch of classes of “theorem types” which will prepend the item with that type followed by a theorem number.

.algorithm, .claim, .corollary, .definition, .example, .lemma, .proposition,
.theorem {
    &::before {
        counter-increment: theorem;
        content: attr(class) " " counter(section) "." counter(theorem) ". ";
        font-weight: bold;
        text-transform: capitalize;
    }
    &[data-ref]::before {
        content: attr(class) " " counter(section) "." counter(theorem) " (" attr(data-ref) ").";
    }
}

Proof environment

Just like theorem numbering, I used to manually set the halmos, which was not great. Again, using CSS, one can make those things work. Since a proof typically involves multiple paragraphs, I define a class .proof for use with a <div> which contains a proof. The CSS will prepend the first paragraph inside the div with Proof. and append a halmos to the end of the final paragraph, which will appropriately float to the right.

.proof p {
    &:first-child::before {
        content: "Proof. ";
        font-style: italic;
    }

    &:last-child::after {
        float: right;
        content: "\25A1";
        font-size: 1.25em;
    }
}

Big challenges

For the most part, everything up to now has got me 98% of what I needed in terms of complicated mathematical typesetting. However, there was one course that really challenged me with weird constructs that I needed to typeset.

That course was CS 245: Logic and Computation, at the University of Waterloo. There were two particularly challenging constructs. The first was Jaśkowski-style natural deduction proofs. These don’t seem so bad at first: each line is numbered, with the rule applied aligned on the right. However, they have a quirk that makes it impossible to use with, say, the \align* environment: when an assumption is made and a subproof is started, the entire subproof is contained in a (literal) box. See here for some examples of how this turned out.

The other construct is verification proofs of code using Hoare logic. The main challenge is that proofs of Hoare logic involve interleaving logical statements with lines of code. See here for some examples. (There was also a minor challenge with including special brackets that aren’t found in TeX’s vast collection of mathematical symbols)

Despite being fairly kludgy, both types of proofs were surprisingly readable and look quite nice.