How to best present alternative ways to write a piece of code (in a slideshow)?

Question

I'm working on a 'slideshow'-type presentation (e.g. using LO Impress) which involves me showing people different alternatives for writing some pieces of software code.

We're not talking about large pieces: Some of the changes I suggest are alternative formulations of individual lines; others involve transforming blocks or loops of several lines; and the largest ones are still under 20 lines or so.

I'm wondering about essentially all aspects of doing this:

• Whether to put "option 1" vs "option 2" on the same slide, or on separate slides

• Whether changes should be made by:

  • me deleting words and writing in new ones, or
  • switching to the next slide
  • automated animation effects (like fades or wipes or a pen striking out text)

• How much change to allow between consecutive slides: Many transitions with tiny self-explanatory changes, or fewer transitions where you tell the audience roughly what happened

• Whether I should even use the presentation software for the actual code, or perhaps switch to an editor, IDE or diff tool between pre-created files

• Choices of color scheme, font size (too small = difficult to read, too big = few lines on the slide, need to memorize), inter-line spacing, margins etc - for maximizing readability.

So, my bottom-like question is: What have you found works well, or works poorly when presenting alternative pieces of code, or necessary transitions on existing code?

Note: The audience can assumed to be coders of various degrees of proficiency.

Answer 1

You have encountered here one of the numerous issues with slideshow presentations as a medium to communicate information. PowerPoint and similar tools are very tricky to impossible to use because of several limitations. Among them:

• Small resolution (when you project the presentation into a wall, you can't use small fonts or detailed illustrations).

• Separation of content into slides, where one and one only slide can be shown at the same time.

In your case, twenty lines of code may fit on a tiny little slide, but forty cannot. If your intention is to show small changes to a piece of code, you could illustrate those changes through a diff. However, from my understanding of your question, you're showing two rather distinct pieces of code, which means that a diff wouldn't be appropriate here.

In The Cognitive Style of PowerPoint, Edward R. Tufte suggests an alternative to slideshows that could work in your case: print the source code on paper, and distribute it to the participants at the beginning of the meeting/conference.

To make it easier to follow your talk and be able to compare the pieces of code:

• Carefully pick a layout. In some cases, portrait would work better. In others, landscape is the best choice. For instance, if you need to show how a clever refactoring allowed you to go from twenty LOCs down to ten, landscape mode would work better in terms of visual comparison.

• Always add the line numbers. Always. It is extremely annoying both for the person from the audience asking you the question and yourself to be here in front of thirty programmers to try to figure out what line of code the person is talking about. “No, I mean, not the first loop, but the line just before the condition in the second loop, no, not this one, but the one after that…”

• Always use syntax highlighting (make sure you use a white background, however, to save ink).

• When needed, don't hesitate to enrich the source code with arrows, legends, rectangles delimiting the zones of interest, etc.

Example of a decorated piece of code in a context of an explanation of why for and foreach are completely different constructs in C#. The digits in circles have the same role as line numbers: to be able to pinpoint a specific place in code.

Answer 2

There is no one-size-fits-all answer here, because the content and focus of your presentation can dramatically impact what conveys the message better.

In all cases, I suggest minimizing the code on screen as much as you can. Presentations are not reading exercises, and a lot of people can't read one thing while listening to another.

Whether to put "option 1" vs "option 2" on the same slide, or on separate slides

If you're comparing things, putting them next to each other makes a lot of sense, instead of blindly relying on people's memory. However, depending on how simple the code is, this may be an irrelevant distinction.

It also helps to keep the content of a slide thematically linked. All snippets on the same slide should yield the same result (or a clearly labeled bad/good comparison), rather than showing different kinds of things all at once.

Whether changes should be made by:

• me deleting words and writing in new ones, or

This seems more fitting for a coding demo, rather than something you do on the slide. Practical demos are a great tool for showing developers their day-to-day interaction with this new thing (e.g. how to go about upgrading the old code), but these demos take time, have an annoying habit of breaking right when everyone's eyes are on you, and become less relevant for trivial things or theoretical discussions.

• switching to the next slide

That is usually how presentations work. You only really switch between slides.

• automated animation effects (like fades or wipes or a pen striking out text)

Animations are distractions. However, they can, when used sparingly increase the joy factor, which can help sweeten the proverbial bitter pill that is a dry and boring topic.

Professionally, I would steer away from animations, barring some very select use cases. But even then, I would heavily favor creating two separate (duplicate) slides with minor differences. This will make more sense for someone reviewing the presentation afterwards, and it allows you to easily toggle between the two if someone has a question about it or if you need to re-explain something.

How much change to allow between consecutive slides: Many transitions with tiny self-explanatory changes, or fewer transitions where you tell the audience roughly what happened

If you change more than [X], then it's not a same slide with differences anymore, it's just a different slide altogether. In order to find [X], we'd first need to consider whether distinguishing between the two is actually productive here, which I don't think it is.

What's more important, though, is that you mark the changes. Change their (foreground) color, highlight them (i.e. change the background color), circle them, change the size, bold them, grey out the code that hasn't changed, ... Whatever makes the most sense to visually mark them without detracting from its readability. The best markup is unintrusive and subtle yet clear.

Whether I should even use the presentation software for the actual code, or perhaps switch to an editor, IDE or diff tool between pre-created files

I refer back to the earlier point about demos. They can be useful, but in the right context. I would reserve demos for cases where you're actually trying to teach a practice, i.e. something you want your attendees to be able to do (not just know) after having seen the presentation.

Choices of color scheme, font size (too small = difficult to read, too big = few lines on the slide, need to memorize), inter-line spacing, margins etc - for maximizing readability.

This depends on the room you're presenting in, screen size, complexity of the text you'll be showing, and even time of day and average age of the attendees can factor into this. There is no singular answer here.

As per most style guides, use a well-contrasted palette, stick to a handful of accent colors (two is usually more than enough), and remain consistent about your palette across the slides.
I would also suggest that you use a different font for the code, preferably mimicking the IDE that is commonly used (for the topic at hand).

Also, as much as most developers love dark mode, don't use dark mode screenshot on a slide with a white or light background. Stick to a similar brightness. Don't forget that what's clear and crisp on a monitor when designing the slides isn't always visible on a projector in a half-lit room.

For any important presentation I've had to do, I actually do a dry run, just to check if the presentation's design works on the screen/room in question (or, if not possible, any setup that simulates the experience).
It's usually only a matter of changing the font size or upping the contrast a bit, but these things are much better tested in the actual room than theorized about.

and the largest ones are still under 20 lines or so.

You seem to imply that 20 is a reasonably upper boundary. For a big room presentation, it isn't.

Don't put too much on a single slide, and most definitely don't start making them into reading exercises. The slides should be summarizing what you say, rather than you explaining what's on the slide.

However, if you're giving a small room presentation, e.g. 4 people around a table, with a large (think >60") monitor nearby or a large projector screen, then you could get away with a 20 line snippet, as long as you slowly walk through it one step at a time, picking apart and individually addressing all of the pieces of the code that are not trivial.
Whether or not it's better to separate the content into single slides is very contextual based on whether the broken up parts make individual sense.

Answer 3

Your current focus is on the "user interface" of your meeting: how should the audience see the alternatives. What about shifting the focus on user experience : how will my audience get engaged into decision making?

Designing the engagement is less critical in a physical meeting. Human beings have a facility to connect with each others and your sole presence can save the game. But in a remote meeting, engagement is very different and needs to be designed with care. It is important to keep the audience active:

• Death by powerpoint? Oh, you can show anything with powerpoint. Even code, even in very small characters. You can even animate the code in fancy manners. But for the brain, it's like a TV-show: most of the audience will instantly switch into a comfortable "listening mode" that is far from ideal for decision making (unless you have a decision ready and just want them to nod).

• Keep stimulating the brain? Instead you can create dynamics in your meeting, by switch from conference mode to shared-screen mode back and forth. And here, sharing your editor on screen for a live demo can make a difference:

  • A part of your audience will recognize the editor, and their brain will send them the message: "Hey, work for you!". And this will create focus and thoughts.
  • You'll give the explanations in a lively fashion: this will create a real discussion. And nothing prevents you from showing a powerpoint slide in the end to summarize in a table the pros and cons of the different options. You could even use some interactive whiteboards such as Mural or others to get your audience complete the pros and cons.

An interactive meeting design requires you to be comfortable with the videoconferencing tool, e.g. switching back and forth between the windows. It's more thrilling for you but also more entertaining for the audience. Important advice: get prepared, and rehearse if you've never done it that way before.