Tips & Tricks for Documentation

Created Friday December 09, 2022

This document contains tips and tricks for writing better documentation. In particular, it focuses on methods for adding better graphical content to documentation.

Record Terminal Output To GIF

https://github.com/asciinema/asciinema
$ brew install asciinema
https://github.com/asciinema/agg
$ cargo install --git https://github.com/asciinema/agg
1: Begin the recording
$ asciinema rec name.cast --cols 90

This will start a new subshell where all input and output is recorded.

2: Run your example command

asciinema will be recording any commands you enter as input to the terminal, and any output generated by those commands. Run your example command by entering it in the normal way.

3: End the recording

Two straightforward ways to end the recorded asciinema subshell are:

Enter the exit command.
Send an EOF (End Of File) character, typical input by typing <CTRL-D>.

Option (2) has the nice advantage of being invisible in the recording of the terminal session, which makes for a cleaner video.

4: Convert to GIF
$ agg name.cast name.gif --theme solarized-light

Other useful flags include:

--speed
--last-frame-duration

Record Screen Capture to GIF

macOS: https://cleanshot.com
macOS: https://giphy.com/apps/giphycapture

Showing Keystrokes On Screen

Keystroke Pro — https://apps.apple.com/app/id1572206224?ct=ixeaujjk