Ten ways to document terminal commands

Shane Crowley

Technical Author @ Canonical
source repo

Command Line Interface

"Simple", flexible, powerful, configurable, scriptable, pastable

Graphical User Interface (try it!)


  • "Easy"
  • Intuitive
  • Mouse-based
  • Visual
  • Non-scriptable

Conversational style


" Just run a mkdir, cd into the directory, create a hello.py and run the Python interpreter... "

Has a certain flow, but assumes prior knowledge.

`In-line`

First mkdir test then cd into test

Now echo "print('hello world')" > hello.py

Finally run python3 hello.py


Good for short and well-known commands but can get messy!

```Code block```

Run the following commands to create a test directory and run a "hello world" script 


						mkdir test
						cd test
						echo "print('hello world')" > hello.py
						python3 hello.py


Highly configurable and often the best option.

Code blocks

First make a directory called 'test' 


						mkdir test

Now change into the directory you just made 


						cd test

Write a basic "hello world" script to a file 


					echo "print('hello')" > hello.py

Run the script


					python3 hello.py

Breaking things up can help with explanations.

Screenshots

Screenshot of a hello world program created and run in the terminal. A directory called test is created, we change into that directory, echo the code into a python file called hello and then run the program.
Process: VM, run commands, screenshot(s), crop, compress, alt text... Good and consistent screenshots take work!

Generated images

Command line: carbon-now hello-py.sh

Screencasts


Example: a popular personality navigating a complex graphical interface. Question: what is the value proposition for documenting terminal commands?

Video as text

Text can be copied, but does the user know? Video has source text, but is it readable? Let's see... 
[1.331381, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                             \r \r"]
[1.33409, "o", "\u001b]2;edibotopic@punctum:~\u0007\u001b]1;~\u0007"]
[1.339865, "o", "\u001b]7;file://punctum/home/edibotopic\u001b\\"]
[1.400018, "o", "\u001b[?1h"]
[1.400214, "o", "\u001b[?2004h"]
[4.542409, "o", "m"]
[4.547491, "o", "\bm\u001b[90mv screenshot3.png ../dev/gh-me/reveal-ubuntu/img\u001b[39m\u001b[48D"]
[4.757369, "o", "\u001b[90mdir test\u001b[39m\u001b[8D"]
[5.006197, "o", "\u001b[39md"]
[5.141599, "o", "\u001b[39mi"]
[5.303773, "o", "\u001b[39mr"]
[5.432706, "o", "\u001b[39m "]
[5.534983, "o", "\u001b[39mt"]
[5.714551, "o", "\u001b[39me"]
[5.882683, "o", "\u001b[39ms"]
[6.083242, "o", "\u001b[39mt"]
[6.78009, "o", "\u001b[?1l"]
[6.780865, "o", "\u001b[?2004l\r\r\n"]
[6.782986, "o", "\u001b]2;mkdir test\u0007\u001b]1;mkdir\u0007"]
[6.789413, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                             \r \r"]
[6.792451, "o", "\u001b]2;edibotopic@punctum:~\u0007\u001b]1;~\u0007"]
[6.80433, "o", "\u001b]7;file://punctum/home/edibotopic\u001b\\"]
[6.860503, "o", "\u001b[?1h\u001b[?2004h"]
[7.326691, "o", "c"]
[7.334353, "o", "\bc\u001b[90mls\u001b[39m\b\b"]
[7.538661, "o", "\bc\u001b[39md\u001b[39m \b"]
[7.545685, "o", "\u001b[90m img\u001b[39m\b\b\b\b"]
[7.652102, "o", "\u001b[39m "]
[7.8068, "o", "\u001b[39mt\u001b[39m \u001b[39m \b\b"]
[7.813279, "o", "\u001b[90mest\u001b[39m\b\b\b"]
[7.988111, "o", "\u001b[39me"]
[8.160896, "o", "\u001b[39ms"]
[8.379006, "o", "\u001b[39mt"]
[9.055901, "o", "\u001b[?1l"]

Video as code


						# test.tape
						Type "mkdir test"
						Sleep 500ms
						Enter
						Type "cd test"
						Enter
						Sleep 1s
						Type `echo 'print("hello world")' > test.py`
						Sleep 1s
						Enter
						Sleep 2s
						Type "python3 test.py"
						Sleep 500ms
						Enter
						Sleep 2.5s
Command prompt showing...

Readable source and can be automated
Command line: vhs myScript.tape

Interactive terminal


Docs are web-based, we can get creative ...but should we???
Note to reader: try `ls`, `cat hello.py` and `python3 hello.py`

Real, complex example

            
              PS C:\Users\myuser> $env:WSLENV="USERPROFILE"

              PS C:\Users\myuser> ubuntu.exe

              $ echo $USERPROFILE

              C:\Users\myuser

Bespoke code blocks

  1. Regex to isolate/exclude prompt from copying
    2.               
                ^.*?[\$>#]\s+
  2. CSS to disable copy button in output blocks
    3. 
              div:not(.no-copy) > div.highlight > pre


In Sphinx, these are set as variables in custom_conf.py

Wrap-up

  • Commands are "simple" to document
  • Trade-offs between methods of representation
  • Better and worse ways to use each approach
  • Need clear reasons for unconventional methods
  • Think: functionality, accessibility, maintainability