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
$ brew install asciinema
$ cargo install --git
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:


Record Screen Capture to GIF


Showing Keystrokes On Screen

Keystroke Pro —