Do you use the right character for replaceable text placeholders?

Email templates are an awesome way to help people save time writing emails. Often the template needs to indicate a piece of text that should be replaced with custom content. When you need to identify text that should be replaced (e.g. in an email template), it's important to use a consistent way of indicating the replaceable text with a placeholder.

Use a consistent character to make it clear which piece of text should be substituted.

However, everyone has their own preferences about which placeholder character to use 🥸

For example:

• SSW Rules historically used xxx
• SSW Intranet | Sales templates use ❌❌❌
• SSW GitHub Sprint Templates use ✏️xxx
• SQL developers are used to [ ]
• Word Mail Merge users are used to « »
• API and React developers are used to { }
• Angular developers are used to {{ }}
• Visual Studio code reviewers are used to TODO:

Let's see these in action:

• The quick brown fox xxx over the lazy dog
• The quick brown fox ❌❌❌ over the lazy dog
• The quick brown fox ✏️xxx over the lazy dog
• The quick brown fox [ action ] over the lazy dog
• The quick brown fox « action » over the lazy dog
• The quick brown fox { action } over the lazy dog
• The quick brown fox {{ action }} over the lazy dog
• The quick brown fox {{ ACTION }} over the lazy dog (currently the standard in SugarLearning and SSW Rules)
• The quick brown fox TODO:action over the lazy dog

More info on the origins

[] are commonly used to label things. On sensitive emails, the text [Sec: Official] gets appended or prefixed to the subject, for example.

Using [] for replaceable text can be confusing since there is already the common usage for labelling.

{ } are used frequently in popular APIs like Microsoft Graph, Microsoft PowerPlatform Facebook, Riot, Amazon and also in React

Angular interpolation uses {{ and }} as a delimiter. They indicate a variable and we think this is a very clear way to indicate that something needs to be replaced because it is very uncommon to see this syntax outside of Angular code.

So, double curly brackets are recommended instead of square brackets to indicate replaceable text.

In certain places such as Sales templates, you cannot afford to miss a single placeholder

Of course, if you want to make it even more obvious then highlight the text in yellow... however you can't do it in many places like Microsoft Forms... so another option is to use an emoji like the ✏️ or to make it super obvious the three ❌❌❌

Another way to draw attention to text is to make the placeholder all caps.

Replaceable text is often seen in email templates:

❌ Figure: Bad example - Using square brackets for replaceable text

✅ Figure: Good example - Using double curly brackets for replaceable text... with spaces, and words in UPPERCASE