20

We develop an online booking system and it may be embedded in customer websites in an iframe. It is very simple to use, you just include a JavaScript file on the page and call the initialisation method in a script.

In the instructions for website developers (or website admins if they know what they're doing) we indicate that a placeholder value should be replaced with the actual customer reference when they call the code, but we've had support requests come through where people find this confusing.

Here is the opening paragraph of the instructions:

In all of the code examples below, replace [CustomerReference] with the customer reference provided to you when you signed up for the online booking system.

And then a code example looks like this:

<script>
    OurService.initDiary("[CustomerReference]");
</script>

Someone today (a website developer, no less) was requesting support because the system "wasn't working". I checked their site and he had included the square brackets in the function call, replacing the company reference inside it.

Thinking about it, I could see someone misreading the instructions and thinking it was an array, like: OurService.initDiary(["CustomerReference"]);

But I hadn't expected them to leave the brackets in the string itself.

Is it enough just to put a note at the end of the instruction sentence:

In all of the code examples below, replace [CustomerReference] with the customer reference provided to you when you signed up for the online booking system (excluding the square brackets).

Or is there an altogether more universally understood way to indicate this?

I considered removing the brackets altogether, but I suspected it would be more difficult to pick out in the code samples where it should be replaced.

6
  • You may add some words what kind of documentation system you are using or it's limits.
    – Doc Brown
    Commented Nov 7, 2023 at 12:45
  • Yes, that would have been a good idea! But since @Jörg W Mittag's response was very thorough and covers a variety of documentation types, I think it might be good to keep the question less specific and hopefully useful to others. Commented Nov 7, 2023 at 13:06
  • 9
    I would add an example to the beginning of the docs. E.g.: Conventions: In some configuration examples, you must insert your own settings. Placeholders are marked with square brackets: [placeholder]. For example, if this documentation shows key = "[customer id]" and your customer ID is 1234, you would write key = "1234"
    – amon
    Commented Nov 7, 2023 at 13:42
  • 2
    Note that "excluding the square brackets" from the replacement operation, means they aren't changed by replacement, and exist in the result.
    – Ben Voigt
    Commented Nov 7, 2023 at 20:35
  • 2
    Whatever you do, be prepared that some people will still get it wrong. Try not to despair. Commented Nov 8, 2023 at 8:37

6 Answers 6

42

The standard way to deal with a certain part of text that needs to stand out from other parts of text is through typographic means: using italics, boldface, size, capitalization, color, different font faces, etc. (Although beware of accessibility problems, especially when using color – make sure the documentation still works for readers with color-blindness, using text-to-speech screenreaders, or braille readers.) Something like:

<script>
    OurService.initDiary("Insert your customer reference here");
</script>

HTML has the var element for this purpose, for example.

You want the reader to "fill in the blanks", so another option (possibly in combination with the above), is to literally leave blanks for the reader to fill in, something like this:

<script>
    OurService.initDiary("                                     "); // Insert your customer reference here
</script>

[Note: Due to the limited formatting options in Stack Exchange answers, I abused the kbd element and non-breaking spaces above. Please, do not do that. Use appropriate styling, e.g., in your HTML documentation, use CSS.]

In an interactive medium such as a documentation web page or a PDF, you can also ask the reader to fill in their customer reference at the beginning and then show their actual customer reference in all the code examples.

You can combine two or all three of those suggestions.

In all cases, make sure that your documentation still stays accessible, printable, and copy&pastable.

At the very least, a slight refactoring of the example code might already help:

<script>
    const yourCustomerReference = ; // Insert your customer reference here

    OurService.initDiary(yourCustomerReference);
</script>

Note that in my example above, the code is intentionally syntactically invalid. I am not convinced that is a good idea, but it might be worth a try.

7
  • Thank you for the detailed answer. I had previously written a comment (since deleted) explaining that I was unable to format code blocks typographically in the current documentation (literally just a forum), but I have since discovered the option to switch to source code view in the editor. Commented Nov 7, 2023 at 12:56
  • Of the three options, I think the first one (using typography) is the way forward, as (to me) it appears clear and explains what should be replaced at the site it should be replaced. The HTML var element is new to me, so thanks for that! That will improve the content semantically and makes it easy to target the correct content in styles. Styling to show a literal gap is a nice idea, but this requires a comment after the line, which isn't so nice, to me. The last option is good too, but I can imagine that intentionally invalid code in the documentation may cause more harm than good. Commented Nov 7, 2023 at 12:59
  • 8
    For code examples, refactoring so that the input variables are explicitly defined is actually a far better approach to the code in general. Commented Nov 8, 2023 at 4:40
  • The variable option was what I was thinking, but the problem in javascript is that it's not clear from the variable declaration that the expected type is string. Maybe the comment could mention it. Commented Nov 8, 2023 at 21:24
  • 1
    I think one thing I like about the first option is that it uses regular sentence formatting (i.e. a prompt with spaces between each word). The OP doesn't have spaces and the brackets make it look like the expected value is code. I have worked on applications where an argument is a string type which can be code which is dynamically reinterpreted. So I might have thought that [CustomerReference] is automagically updated with my reference number. Commented Nov 9, 2023 at 15:10
20

I fully support Jörg's answer and recommend the usage of <var> elements with appropriate styling.

However, to prevent the mistake of copying the square brackets and writing an array literal, you could also use a different bracket type. While square brackets are the most common representation for "fill-in" parameters1, you can also use <…> angle brackets or {…} curly braces (which are common in template syntax). Those have the advantage of producing a syntax error in JS if they do not get replaced.

Another option is to use a syntactically valid format in the code2, but with a value that is void or semantically invalid. It should be easily distinguishable as an example value, like "customer-ref.example.com", "00000000-0000-0000-0000-000000000000" or "12345678-1234-5678-1234-567812345678". In your code, you may even throw an exception with an explanatory message when it is called with this sentinel value passed.

1: not to be confused with their usage in API signature documentation, where they mark up optional parameters.
2: of course still with the instruction to replace that value by the customer reference.

4
  • 4
    This is what I tend to do, it works well in other languages as well. Make the sample code clear but syntactically invalid unless you fill in the blanks like you're supposed to. Let the compiler flag the problem early. Depending on the language, I'll surround pseudo-variables with <<<triple_arrows>>> or 【lenticular_brackets】. Visually clear, yet no chance at being run.
    – bta
    Commented Nov 7, 2023 at 22:48
  • 4
    I am ready to bet there are thousands of objects with UUID 12345678-1234-5678-1234-567812345678 in the wild. In my experience, unless the value makes the software throw a hard error, a significant portion of users will never change it.
    – spectras
    Commented Nov 8, 2023 at 14:39
  • @bta One benefit of <<<triple arrows>>> is that (depending on language) it visually stands out when scanning/proofreading the document. (And in contrast to bold/italic formatting, it persists when copy/pasted.) That makes it easier to see where you might have missed the substitution.
    – R.M.
    Commented Nov 8, 2023 at 17:25
  • 3
    I tend to use special characters that are not used by the languages, like «example». Brackets or arrows tend to give confusion error messages and can break auto formatting. Words wrapped with invalid characters are easy to detect as invalid tokens and produce more straight-forward error messages.
    – kapex
    Commented Nov 8, 2023 at 17:57
8

A bit of a frame challenge.

What you have made is a software library. So the documentation should not just provide examples, it should document the customer-facing API of the library. There are millions of examples of API documentation, but no decent API documentation relies on examples only. And even the examples are usually with some made-up values, not with placeholder.

So you can write something like:


The library provides a single global class instance, OurService.

This class has the following methods:

  • initDiary(customerReference: string)

    Accepts one paremeter, the customer reference string (in "CUSTOMER1234" format). Initializes the diary. May be called only once before a corresponding call to closeDiary.

  • closeDiary()

    Closes the previously-initialized diary.

  • etc....

Example:

<script>
    OurService.initDiary("CUSTOMER1234");
    someButton.onClick = closeDiary;
</script>

This is a more-or-less standard way of describing APIs that every developer should understand.

Also, if do not want do document all the methods and parameters of your classes, then maybe you should create a customer-facing wrapper that will expose only the methods and parameters that you want to expose.

4

Here's an overview of the approaches taken by some of the tech giants:

  • Microsoft shows the syntax of Powershell cmdlets (e.g. Get-TimeZone) using angle brackets whenever an argument must be specified by the user, and as placeholder they use the argument's type , such as <string[]>:

    Get-TimeZone
       [[-Name] <String[]>]
       [<CommonParameters>]
    
  • Git's documentation uses angle brackets for variables:

    git branch (-m | -M) [<oldbranch>] <newbranch>
    
  • Grep's manual on gnu.org writes the placeholders in italics:

    -f file
    --file=file

  • Google has a very nice solution which makes heavy use of text formatting: when describing commands, the docs for Cloud Shell write variables in italics and use a different colour and background, and then when they show the code they write the placeholder using the same colour, underlining it with some dots and adding a pencil icon which can be clicked to edit the value:

    Example of Google's style when describing the syntax of a command containing a placeholder that must be replaced by the user

  • Some companies sidestep the problem entirely, as they do not provide a synopsis with placeholders; instead, they always give examples using real values:

    • IBM in their tutorial on AWK

    • Red Hat in their article about essential Linux commands. There's one exception, though: when talking about the kill command they use angle brackets:

      $ kill -15 <PID>
      
    • Apple in their shell scripting tutorial. Again, there's one exception: when talking about case they use some placeholders

      case expression in
          [(] value | value | value | ... ) command; command; ... ;;
          [(] value | value | value | ... ) command; command; ... ;;
          ...
      esac
      

      In this case the formatting is the same, so it is up to the user to figure out that these are placeholders. The context makes it clear, and the fact that these keywords are repeated helps.

1

An option I've used is to insert an actual comment. Many editors will use a different color for this, so it stands out.

<script>
    OurService.initDiary(<!-- CustomerReference -->);
</script>

If this is overlooked, you can reasonably expect an error message along the line of "Missing argument in call to initDiary. 1 argument expected, but 0 provided."

-1

Rip a page out of Gerrit’s playbook:

Screenshot of Gerrit showing a list of git clone commands

Or YouTube’s playbook:

Screenshot of YouTube showing the embed code popup

In other words, don’t ask your customers to replace any placeholders. Give them the actual, literal code they need to insert, ready to copy-paste, save and forget it. Computers exist to do clerical work like this, so let them do it. Put it somewhere on their account page when they log in to your service, and have documentation direct them there. That simple.

(Those are not particularly fresh screenshots, but it doesn’t matter. Principle remains the same.)

Failing that, you can have a section on your site that lets the user enter their reference number and it spits back a ready-made snippet to copy-paste. Something as simple as this will do:

const input = document.getElementById('refnum');
const output = document.getElementById('output');
const inputSec = document.getElementById('refnum-section');
const outputSec = document.getElementById('output-section');

inputSec.style.display = '';
outputSec.style.display = 'none';

input.addEventListener('input', ev => {
    outputSec.style.display = input.value !== '' ? '' : 'none';
    output.textContent = JSON.stringify(input.value);
});
<p id="refnum-section" style="display: none;">
  Enter your customer reference number here:
  <input id="refnum" placeholder="123456789-ABCDEFGHI">

<div id="output-section">
  <p> Insert this snippet into your site:

  <pre>&lt;script type="text/javascript">
  OurService.initDiary(<span id="output"><var>"your reference number here"</var></span>);
&lt;/script></pre>
</div>

Modulo, of course, however you can fit the above interface into your shiny frontend framework of the week. (This would have been a runnable snippet, but those aren’t enabled on this site for some reason.)

Not the answer you're looking for? Browse other questions tagged or ask your own question.