Documenting Code

Clear, well-documented code improves readability, reduces user error, and builds user confidence. Code examples should help users understand what to run, why they are running it, and what to expect.

These guidelines apply to all code examples, including commands, configuration files, scripts, file excerpts, and sample output.

Because many users are not full-time developers or system administrators, code must be documented clearly and concisely, with minimal assumptions about prior context.

General Code Guidelines

Code samples must follow these principles:

• Be readable and concise.
• Be easy to copy and run without major modification.
• Be accessible to users with varying levels of technical experience.

Use the following guidelines consistently when writing and reviewing documentation:

• Specify the language for all fenced code blocks.
• Introduce each code block with a brief explanation of what the code does, where to run it, and what to expect as a result.
• Do not place a code block immediately after a heading.
• Do not include code without an explanation.
• Include code only when it is necessary to complete the workflow.

Placeholders and Variables

Use angle brackets for placeholders, for example <your-droplet-name>.

Avoid curly braces {} or square brackets [], as they often represent syntax.

Do not include placeholder symbols that may break commands or configurations.

Explain placeholders the first time they appear, if needed.

Inline Code Formatting

Use inline code formatting for:

• IP addresses and domains
• Commands and subcommands
• Package names
• Filenames and paths
• Environment variables
• Options and flags
• Input field values
• Key names and keyboard shortcuts

Input Field Values

Format input field values inline, not as commands or code blocks.

Use inline code formatting when referencing values that users enter into UI fields, forms, or configuration inputs. This helps distinguish data from actions.

For example:

• Enter example.com in the Domain field.
• Set the Region to nyc3.
• Use my-bucket-name as the bucket name.

Do not present input values as standalone commands or fenced code blocks unless the value is part of an executable command or configuration file.

Key Presses and Keyboard Shortcuts

Document key presses and keyboard shortcuts following the Microsoft Style Guide:

• Capitalize key names.
• Use + without spaces to indicate combined key presses.
• Use inline code formatting for keys and shortcuts.

For example:

• Press Enter to submit the form.
• Press Ctrl+C to stop the process.
• On macOS, press Command+S to save the file.

Do not format key presses as code blocks or include them in shell examples.

Documenting Commands

Prefer fenced code blocks for most examples. Use the highlight shortcode only when you need Hugo-specific features, such as line highlighting or line numbers.

Use inline code formatting for optional or alternative commands.

Do not include shell prompts ($ or #). Commands must be directly copyable.

Use a backslash (\) at the end of each line when breaking a long command across multiple lines.

Introduce each command with a short explanation, and then follow with additional detail as needed.

For example:

Display the contents of the /home/sammy directory, including hidden files:

ls -al /home/sammy

The -a option includes hidden files, and the -l option displays file metadata such as timestamps and sizes.

Commands Requiring Elevated Privileges

Prepend commands that require elevated privileges with sudo.

sudo ufw enable

This promotes safer defaults and avoids instructing users to log in as the root user.

Command Output

Include sample output only when it helps users:

• Confirm success
• Validate results
• Understand expected behavior

Display output in a separate code block and label it clearly.

For example:

Run the program:

node hello.js

You should see the following output:

Output
Hello world!
This is my first Node.js program!

Documenting Files and Configuration

Always explain the purpose of a file before showing its contents.

Explicitly tell users which file to create or open.

Introduce file-based examples with a label line.

For example:

File: /etc/nginx/sites-available/default

server {
    listen 80;
    server_name example.com;
}

Editing Files from the Command Line

When the reader is expected to use the command line:

• Instruct them to open the file using a single command.
• Use pre-installed editors (nano on Ubuntu/Debian, vi on CentOS/FreeBSD).
• Do not use touch to create empty files before editing.

For example:

Open the configuration file:

nano /etc/nginx/sites-available/default

When the reader is not expected to use the command line, clearly state which file to open instead.

Documenting Code Samples

When asking users to write or review code:

1. Explain what the code does at a high level.
2. Show the code.
3. Call out important details, inputs, or constraints.

For example:

The following Go example creates a new block storage volume using the API:

import (
    "context"
    "os"
    "github.com/digitalocean/godo"
)

This request defines the volume name, size, and region before creating the resource.

Formatting and Highlighting

Hugo supports syntax highlighting through its integration with Chroma.

• Use fenced code blocks or the highlight shortcode.
• Choose the correct language identifier to improve readability.
• Do not include screenshots of terminals, editors, IDEs, or third-party tools.

For a complete example of well-formatted code, see the NAT gateway tutorial.