Code Style in Text — Formatting Code References in Technical Documentation

In this tutorial, you will learn about Code Style in Text. We cover key concepts, practical examples, and best practices to help you master this topic.

Code appears throughout technical documentation in various forms. Inline code references, code blocks, commands, variables, and file paths each need consistent formatting. Proper code formatting helps readers distinguish code from prose.

In this lesson, you will learn standards for formatting code references in technical documentation.

What You'll Learn

You will understand when to use inline code VS Code blocks, format commands and file paths correctly, and maintain consistent code formatting.

Why It Matters

Inconsistent code formatting confuses readers. Readers cannot tell whether compress_file is a command, a function name, or a file.

Real-World Use

DodaTech standardized inline code formatting using backticks for all code references. This rule eliminated ambiguity about what is code and what is prose.

flowchart LR
  A[Code in Text] --> B[Inline Code]
  A --> C[Code Blocks]
  A --> D[Commands]
  A --> E[Variables]
  B --> F[Use backticks]
  C --> G[Use fenced blocks]
  D --> H[Bold or backticks]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Inline Code

Use backticks for inline code references. Use compress_file not compress_file in prose.

Use inline code for function names, variable names, parameter names, file names, and short code snippets.

Do not use inline code for product names, UI labels, or general technical terms. Use bold or plain text instead.

# Good inline code usage
Call the `compress_file` function with the `input_path` parameter.
Save the output to `data.csv.gz`.
Set the `algorithm` variable to gzip.

# Bad inline code usage
Install the `DodaZIP` package. (use bold instead)
Click the `Save` button. (use UI label formatting instead)

Code Blocks

Use fenced code blocks with language tags for multi-line examples. Always specify the language for syntax highlighting.

Show expected output after code blocks. Readers need to verify their results match.

Keep code blocks focused. Show only the relevant code. Do not include boilerplate that distracts from the point.

# Good code block with language tag and expected output
def add(a, b):
    return a + b

result = add(3, 5)
print(result)
# Expected: 8

Common Mistakes

1. No Backticks for Code References

Writing function_name in plain text instead of function_name. Readers cannot distinguish code from prose.

2. Overusing Inline Code

Putting product names and UI labels in backticks. These should use bold or plain text formatting.

3. No Language Tags

Code blocks without language tags do not get syntax highlighting.

4. Inconsistent Command Formatting

Formatting commands with backticks in some places and bold in others.

5. No Expected Output

Code blocks that show code but not what the reader should expect.

6. Code Blocks Too Long

Code blocks over 20 lines that readers skip. Break into smaller blocks.

7. Formatting File Paths Inconsistently

Writing /path/to/file with backticks sometimes and without other times.

Practice Questions

1. When should you use inline code?

For function names, variable names, parameter names, file names, and short code snippets.

2. When should you use code blocks?

For multi-line code examples that readers might copy and run.

3. Why specify language tags in code blocks?

For syntax highlighting. Without a language tag, the code block appears as plain text.

4. What should follow every code block?

Expected output so readers can verify their results.

5. Challenge: Find 10 code formatting inconsistencies in a documentation page. Fix each one applying consistent rules.

FAQ

Mini Project

Create a code formatting style guide for a documentation project. Include rules for inline code, code blocks, commands, file paths, variables, placeholder values, and error messages. Provide examples.

What's Next

Next: Cross-Referencing