Code formatting guidelines: var and mark

This document serves as a supplement to the basic <var> and <mark> documentation. It gives a longer explanation of when to use the <var> and <mark> formatting styles, and reasons for not using them.

var: Highlight user-specific values in procedural code snippets

The <var> tag is used for user-input values in code snippets that customers would be using in procedural/functional ways. For example, you would use the <var> tag when explaining how to do some specific task.

A <var> tag would not be used for:

• Example code: If the code is meant to be an example, to show the format/structure of the code, and there is not an actual procedure the customer is following, var tags are not needed. Examples:
  • Example configuration file (or this Java agent config template): if you are showing an example config file that isn't part of a procedure, you shouldn't use the <var> tag. Several reasons for this: 1) The important part of showing an example config file is to show the overall structure of the file, 2) Usually the number of config options present in a file will vary based on whatever the customer wishes to use, so using <var> tags can actually be confusing as it implies that these values must be present.
  • Instrumentation procedure (at bottom of the Java section): the var tag wouldn't be necessary because it's an example, not part of a procedure, and the main goal is seeing the general structure. Also, because it's an example of app code, the concept of user-specific values doesn't have much meaning, because the entire code will vary dependent on how the customer has written their code. (If anything, this would be a potential for using <mark> format to emphasize the New Relic functions.)
• Response/output code: If the code is meant to show an expected return, and is not related to a procedure, then var tags shouldn't be used. Here's a doc section (the returned JSON) where var tags are not needed.

For an example of a doc section with both <var> formatting and without it, see the Synthetics monitors REST API example. The first block shows a command they might choose to run, hence it uses a <var> tag. The second block is just an example output, showing the structure that would be returned; it doesn't require a <var> tag.

For some use cases, highlighting may be a better choice than a var tag.

var format examples

Below are some general style recommendations for formatting user-specific <var> values. <var> tag formatting may vary based on language- or system-specific expectations, so be sure check the style used in the documentation section in question, and to ask relevant SMEs what they think of the style.

• Account IDs and other IDs/#s: YOUR_ACCOUNT_ID, YOUR_API_CODE, etc. This should be the general style used.

• URLs: example.com, or maybe YOUR_URL

• Paths: PATH/TO/SOMETHING.exe or maybe PATH_TO_FILE

• Emails: datanerd@example.com or maybe YOUR_EMAIL

• Bash variables for REST API code: Some <var> tagged code values on the docs site have the form ${API_KEY}. This is a format used for variables in bash scripts, where users assign values to specific variable names and then call those variables later in the script by using the $VARIABLE_NAME. For more info, see this explanation of bash variables.

  重要

  The bash variable style is currently used in the REST API docs and in some Synthetics docs and that's fine. But going forward we should use the general variable style (without the $ and < >).

mark: Emphasize non-procedure code snippets

Highlighting (<mark>) is used for when you want to draw attention to a variable or value, but it's not something directly procedural related. Here are two examples of highlighting:

• Highlighting values in code response that are meant for later use: Activate Azure integrations doc.
• Highlighting the commands in a large code block example that are New Relic-specific commands, with explanations below: Java API doc.