Documenting Code

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.

Documenting Commands

• 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.

Documenting Files and Code Blocks

• 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.

Formatting

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.

We have syntax highlighting (+ more) support via Hugo’s native integration with Chroma. You can use code fences directly or the highlight shortcode.

This VPC gateway tutorial is a good example of how to format and distinguish code blocks, files, and commands.