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

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

Playback Title and Description

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:

Making Comments

Writing code

Viewing Playbacks

Questions? Comments? Corrections? Contact the BDFL