---

Writing Good Playbacks

The following is some advice about how to write good, meaningful playbacks that comes from the project creator, Mark Mahoney. Please feel free to contact Mark if you would like to add your own suggestions or have comments about these.

The number one piece of advice when creating playbacks is to remember to put yourself in the role of the future maintainer of this code in addition to the author. As you review your code being animated ask yourself why you developed the code the way you did. Imagine what the actual maintainer will need to know in order to fully understand and then build on your code. Describe the essence of the code in the playback from the author's perspective. Then be a generous teammate who explains themselves fully. Use metacognition to explain to yourself why your code looks like it does.

Think About Who Your Audience Is

• Who do you want to reach with the playback?
  • Are they expert programmers or novices?
  • Do they know the programming language well or are they inexperienced with the language?
  • Are they new to the system being developed or do they have experience with it already?
• Create a playback for a single audience:
  • Put yourself in the mindset of who the target audience is and think about what you would like them to know if you were viewing the playback.
  • If there is more than one audience create a separate playback for each one.
• Think about the things that you want the viewer know about the code. Are you showing:
  • a new feature's development?
  • something about the programming language itself?
  • a new algorithm?
  • a refactor?
  • a bug fix?

Attempting to put too much in a playback can lead to complexity that is hard for a viewer to understand.

Playback Title and Description

Choose a title that gives the reader an idea about what they are about to learn from watching the playback.

Provide some context in the description of the playback:

• Describe what the reader will learn from watching this playback
• Describe what the reader needs to know about the problem before they see its implementation
  • Provide context
  • Provide background information
• Don't try and refer to any code directly in the introduction. Use comments to do that.
• Wrap up the introduction with a brief description of the program that the viewer will see in the playback

Making Comments

• Look for interesting things in your code:
  • Not everything that we do is interesting or novel. If it is not interesting don't feel the need to describe it with a comment.
  • Don't forget who your audience is. Expert programmers, for example, probably don't need as much basic information as a beginner does.
• Try to minimize the number of pause points.
  • Batch up groups of related changes and then describe them together with a series of comments at a single pause point rather than describing each change individually at different pause points.
  • This provides more visible context that the viewer can refer to without having to move forward or backward.
• Don't put too much text in a comment. The code in the playback window is the star of the show.
  • Use tweet sized comments if possible.
  • If not possible, separate the text into tweet sized paragraphs.
• Don't forget to highlight the relevant parts of the code.
  • The reader will focus on the highlighted code and the comment together.
  • A playback author can select more than one group of code at a time to highlight. This gives the author much better precision than a typical code comment. One comment might refer to two or more different lines of code on the screen.
• A picture is worth 1000 words.
  • One of the most valuable features of Storyteller is the ability to link pictures to code- use it!
  • The tool lets you create a new picture from a previous comment picture. One can build up pictures that evolve over time.
  • Show screenshots of a program's output after describing an interesting bit of code.
    • Draw on the output of running code to highlight what is important and why it is important.
  • Prefer multiple pics to long text comments.
• Record video comments for complex or subtle points or stories that might benefit from having vocal inflection.
• Use foreshadowing to prepare the viewer for what comes next.
  • For example, after a function header is written add a comment that explains what will happen in the function next.
    • This is a transition and a good place to let the user know what's coming.
  • Before a big jump to a different section of code in the playback provide an indication that it is about to happen.
    • For example, after a method of the Foo class has been played back add a comment that says, "Now I will begin working on a new method in the Bar class that ...".
• Go through the playback repeatedly.
  • Your first pass through code will yield some good comments.
  • By going through a second and third time you will have even more to say about the code.
  • As you go through the playback a second time, edit the existing comments for clarity.
  • Sometimes it takes 4 or 5 times through a playback before there is nothing more to add or edit.
  • Take a break between finishing the code and going through the playback as some time away from it often yields better edits/additions.
• The most valuable comments tend to be at compile/run points.
  • Write code until you get something to work, then reflect and write about what happened.
  • It is safer to comment only after you know for sure your latest work compiles and runs correctly.

Writing code

• It's ok to write some code first without recording it to get your thoughts and ideas together. Practice makes perfect!
  • Showing the order that you did things is more important than showing the viewer that you make typos too.
• Don't include code comments in the code.
  • Normally, I am a big proponent of including code comments in my code but I find them unnecessary when I am creating a playback.
• Write storyteller comments as you are writing code.
  • Don't save all of the commenting until the program is complete. It is too easy to forget interesting context information after a long period of time.
  • Write them as you go when the ideas are fresh in your mind.

Viewing Playbacks

• Make sure your audience knows that they can skip the character-by-character animation.
  • Some viewers prefer to see the code animated but many only want to see the code at the comment points.
  • The playback highlights what has changed since the last comment so the viewer will be able to see what is new.

---