Properly distinguishing and explaining code, commands, and files improves the readability of our documentation and instills confidence in our users.
Our platform caters to small- and medium-sized businesses, many of which don’t employ full-time developers or system administrators, so it’s important to document code comprehensively and concisely.
Use code blocks for commands a reader must run. Use in-line code formatting
for optional or alternative commands.
Print the contents of the file by misusing
cat
:cat file.txt
Alternatively, you can view the contents of the file without printing it to the terminal using
less file.txt
.
Precede every command with a description that explains what the command does. After the command, provide additional details about the command, such as what the arguments do and why your reader is using them.
Execute the following command to display the contents of the
/home/sammy
directory, including all hidden files:ls -al /home/sammy
The
-a
switch shows all files, including hidden ones, and the-l
switch shows a long listing including timestamps and file sizes.
Display the output of commands and programs using a separate code block.
Run the
hello.js
program:node hello.js
You’ll see the program’s output appear on the screen:
Output Hello world! This is my first Node.js program!
The output block has a label and is separated from the command with some explanatory text. Separating the commands from the output makes it clearer to readers where the command ends and the output begins.
Prepend commands that require root or superuser privileges with sudo
:
sudo ufw enable
This promotes the best practice of not logging in directly as the root user. If the reader does already have root privileges, the extra sudo
silently does nothing.
Like commands, always introduce a file or script by describing its general purpose, then explain any changes that the reader will be making in the file. Without these explanations, readers won’t be able to customize, update, or troubleshoot issues in the long run.
Explicitly tell the user to create or open each file you’ll have them use.
In content targeted at command-line users, instruct the reader to create and open the file using a command on its own line:
Open the file
/etc/hginx/config
with the following command:nano /etc/nginx/sites-available/default
We use pre-installed text editors for commands to edit files: nano
on Ubuntu and Debian, and vi
on CentOS and FreeBSD. Don’t use an extraneous touch
command to create new empty files for editing. Instead, create files with the editor directly.
In content where the reader is not expected to use the command-line interface, such as front-end development tutorials, you can omit the command to open the file. However, be sure to tell the reader which file to open explicitly:
Open the file
src/App.js
in your editor.
A reader should always know which file they’re working with.
If you’re asking the reader to write code, follow the same approach for commands: introduce the code block with a high-level explanation of what it does. Then show the code, and then call out any important details.
The following Golang request creates a new block storage volume in your account using the API:
import ( "context" "os" "github.com/digitalocean/godo" ) func main() { token := os.Getenv("DIGITALOCEAN_TOKEN") client := godo.NewFromToken(token) ctx := context.TODO() createRequest := &VolumeCreateRequest{ Region: "nyc1", Name: "example", Description: "Block store for examples", SizeGigaBytes: 10, } volume, _, err := client.Storage.CreateVolume(ctx, createRequest) }
The request requires you to define the volume’s name, size, file system, and the region it will reside in.
In Hugo, code blocks can be syntax sensitive, meaning that Hugo can highlight different pieces of the command’s functionality based on the language in the code block to make it more readable.
To format a command as a fenced code block, use three ticks to enclose the code. To apply syntax highlighting to a command, write the command’s type after the initial tick marks, such as shell
or bash
:
```shell
nano example-file.yaml
```
You can see the full list of languages that Hugo supports in the Hugo syntax highlighting documentation.
When documenting code that exists in a file, such as /etc/netplan/50-cloud-init.yaml
, use the prism
shortcode, which is backed by prism.js. The prism
shortcode offers more functionality than normal code blocks and includes features like block titles, line highlighting, line numbering, and file name headers.
This VPC gateway tutorial is a good example of how to format and distinguish code blocks, files, and commands.