Advanced: Branching Style Guide

This style guide will walk you through best practices for writing Branches. Please note that this guide uses the default logic of writing the first rule that is true. For more information on writing multiple true rules, see here.

Wordsmith Style Guides

Click to see other available Wordsmith style guides

Creating Branches

When should I create a Branch?

👍

Do this:

Create a Branch when you want to change the text in your narratives based on rules using your data. Branches are denoted by blue underlined text in the Wordsmith editor. The image below shows an example of a Branch's rules.

📘

Recommendation:

When simply comparing two Data Variables together as seen above, we recommend using the greater than logic in the first rule, then the less than logic in the second rule, then finally the equals to logic in the third rule. We've found that this is the easiest way for others to follow the logic and that it helps to maintain this order of rules consistently across Branches within a Template or Project.

Why? Branching is one of the most-powerful features in Wordsmith. You can create Branches around words, phrases, sentences, paragraphs, and even entire Templates. Learn more about the difference between required and optional Branches, where to put punctuation in Branches, and how to nest Branches within one another, among other topics below.

Waterfall Method

In what order does Wordsmith evaluate rules?

❗️

Don't do this:

Rule 2 includes unnecessary logic.

👍

Do this:

In order to evaluate Rule 2, Rule 1 has to be false. So high_temp < 90 is unnecessary.

Why? Simplified Branch logic. Wordsmith evaluates rules in a Branch from the top-down. So in order for Rule 2 to be evaluated, Rule 1 has to be false.

Order of Rules

How should I order my rules?

❗️

Don't do this:

Rule 2 would never be true in this Branch. Since Rule 1 is evaluated first, if the high_temp is >= 75, then "pleasant" would be written. If Rule 1 is false, the high_temp can't be >= 90, so "hot" would never be written.

👍

Do this:

Here, the rules are switched so that if the high_temp is not >= 90, then Wordsmith checks if the temp is >= 75. Either "hot" or "pleasant" will be written depending on the high_temp.

Why? Waterfall Method. Wordsmith evaluates Branch rules from the top down.

Inserting Data Variables

When should I insert Data Variables?

❗️

Don't do this:

The rules and text in this Branch can be simplified by inserting a Data Variable.

👍

Do this:

This avoids repetition and substitutes data from any row where this rule is true.

Why? Now you don't have to explicitly account for all possible cases in your data where goals >= 2. By inserting a Data Variable and applying formatting options, Wordsmith handles the rest!

Phrase Branches

Should I create Branch around the full sentence or just a phrase within the sentence?

❗️

Don't do this:

The text in these three sentences is very similar and doesn't need to be repeated in each rule.

👍

Do this:

Instead, you can create a Branch around a phrase within the sentence and still achieve the same result.

Why? This removes the other repetitive words from the Branch. Now, any changes to the static parts of the sentence only need to be made once instead of three times. If the sentences within each rule of the Branch are very different, it's fine to create the Branch around the entire sentence.

Required vs Optional Branches

What's the difference between required and optional Branches and how should I use them?

📘

Required Branches:

A required Branch will always have one of its rules evaluate as true. This can be done in two ways: either all possible logical rules are explicitly accounted for, as shown in the first image below, or the default rule is used to catch all other situations, as shown in the second image.

📘

Optional Branches:

An optional Branch may or may not have one of its rules evaluate as true. If none of the rules evaluate as true, Wordsmith will skip the Branch in the narrative, so make sure that the text still makes sense grammatically in that situation. Optional Branches should also never use the default rule.

Why? Required Branches should be used when you always want the Branch to display something. Conversely, optional Branches should be used when you only want to display something some of the time. Learn more about when to use the default rule, punctuation in each type of Branch, or spacing within optional Branches.

Syntax Spacing

How should my logic within rules look?

❗️

Don't do this:

Leaving no spaces in between your Data Variables and operators in your logic makes it hard to read and interpret.

👍

Do this:

Including spaces makes rules easier to read.

Why? Your logic in rules should be as clear and easy to interpret as possible.

Comparison Syntax

How do I compare values in Wordsmith?

❗️

Don't do this:

This will cause an error because Wordsmith doesn't know what to compare to sales_ytd_avg.

👍

Do this:

Reuse the Data Variable 'sales' as shown below to explicitly compare it to two other Data Variables.

Why? Wordsmith always needs two numerical values in order to do comparisons.

Order of Operations

When do I need to use parentheses in my conditional logic?

❗️

Don't do this:

This rule contains ambiguous logic.

👍

Do this:

Use parentheses to specify the order in which the logic should be evaluated. The first image tells Wordsmith that either the first two pieces of logic need to be true, or the third piece. The second image tells Wordsmith that the first piece of logic and either the second or third need to be true.

Why? You should always use parentheses when needed to make your logic easier to read and interpret.

Ordering Data Variables in Rules

How should I order the Data Variables in my conditional logic?

❗️

Don't do this:

Switching the order of the Data Variables in the logic from rule to rule makes it harder to read and interpret.

👍

Do this:

Maintain the order of the Data Variables being used in each rule, just use the opposite logical operator where appropriate.

Why? This will keep your conditional logic consistent, making it easier to read and understand.

Checking for Blank Cells in the Data

How do I check for blank values or empty cells in my data?

❗️

Don't do this:

The first image below will only work if you have "NULL" strings in your data for empty values, but your data does not need to be formatted this way to work in Wordsmith. The second image is incorrect because Wordsmith doesn't support using "not" as a logical operator.

👍

Do this:

The rule below is checking if the overall_rating field in the data is not an empty string, or not null. In other words, if there is a value for overall_rating, this rule will evaluate as true. Conversely, you could also do overall_rating = "" to say something when rows have blank values for overall_rating.

Why? The only way to check for empty cells in conditional logic in Wordsmith is to check against an empty string, which is notated by two double quotation marks. Learn more about how to use math operators with null checks.

Using A/An

How do I set up Wordsmith to use "a" or "an" appropriately?

❗️

Don't do this:

You don't need to set up a Branch to account for all the scenarios in your data where "a" or "an" should be used appropriately.

👍

Do this:

You can just type "a" or "an" directly in your Template and Wordsmith will automatically use the correct word. In the second image below, you can see the narrative adjusts depending on the value of the Data Variable.

Why? Wordsmith includes built-in a/an functionality that will automatically choose the correct word. It's just one of the many cool features Wordsmith has to help make automating content easier!

Plural Branches

How do I set up Wordsmith to account for singular and plural versions of words?

👍

Do this if your data has only positive values:

Set up a Branch where the first rule is the singular version of the word and the default rule is the plural version of the word.

👍

Do this if your data has negative and positive values:

Similarly, check if the Data Variable equals 1 or -1 in the first rule and then use the default rule to account for the plural version of the word.

Why? Checking for plurality can be done using logic, just like any other Branch in Wordsmith.

Comparing Data Variables to Numbers Syntax

What is the preferred syntax for comparing a Data Variable to a number?

📘

Recommendation:

Use the >= operator instead of >.

Why? Using >= is slightly clearer and requires less interpretation than using just >.

Order of Checking Counts

How should I order my rules when checking for counts within my data?

📘

Recommendation:

Check for counts in descending order.

Why? Always checking for counts in descending order will help make your rules consistent across different Branches and Templates.

Using the Default Rule

When should I use the default rule?

❗️

Don't do this:

Don't write out large blocks of cumbersome logic to account for all scenarios of a Data Variable or Variables.

👍

Do this:

Use the default rule to provide text for all rows that return false for the previous rules in the Branch.

📘

Recommendation:

If the logic is not too cumbersome to write out, we recommend explicitly including it for all possible scenarios within your data. In the image below, all three possible rules are laid out and the default rule is not used.

Why? Using the default rule will save you from typos and make sure that all possible scenarios in your data are accounted for. However, we recommend explicitly writing out the logic where it makes sense for the sake of clarity, especially if other users need to edit your Template.

❗️

Don't do this:

Don't include a blank default rule for optional phrases. It's unnecessary.

👍

Do this:

Avoid using the default rule at all for optional Branches.

Why? Wordsmith will evaluate each rule in order from top to bottom and if none of them evaluate as true, Wordsmith will skip the Branch.

Punctuation in Branches

When building Branches, where should I put the punctuation marks?

❗️

Don't do this for required full sentences:

The two images below show a Branch that contains a full sentence. Since the Branch is required i.e. one of the conditions will always be true, you don't need to include the period in each rule of the Branch.

👍

Do this for required full sentences:

Instead, you can place the period outside of the Branch after the sentence, as seen in the two images below.

Why? Pulling the period out of the Branch reduces repetition and makes it easier to change if necessary. You don't need to worry about missing a period in one of the rules, and if, for example, you want to change it to an exclamation point instead, you only need to make the change in one place rather than multiple places.

Similarly, the same concept applies to required Branches for words or phrases at the end of a sentence.

❗️

Don't do this for required partial Branches at the end of a sentence:

The two images below show a Branch that contains a word at the end of the sentence. Since the Branch is required i.e. one of the rules will always be true, you don't need to include the period in each rule of the Branch.

👍

Do this for required partial Branches at the end of a sentence:

Place the period outside of the Branch after the sentence, as seen in the two images below.

Why? Pulling the period out of the branch reduces repetition and makes it easier to change if necessary.

❗️

Don't do this for optional full sentences:

For optional full sentences though, i.e. where one of its rules is not guaranteed to be true, you don't want to place the period outside of the Branch.

👍

Do this for optional full sentences:

Instead, include the period in the Branch for optional full sentences, as seen in the two images below.

Why? Because the Branch is optional i.e. one of its rules is not guaranteed to be true, there's a chance that no text will display for this Branch. In that case, you don't want a period to display on its own in narrative. To prevent this, include the period in each rule for optional full sentences.

The opposite, however, is true for optional partial Branches at the end of a sentence.

❗️

Don't do this for optional Branches at the end of a sentence:

Punctuation should not be included in rules for optional Branches at the end of a sentence.

👍

Do this for optional Branches at the end of a sentence:

Pull the punctuation out of any rules in optional Branches at the end of a sentence.

Why? Since there's a chance of the Branch being skipped, you'll want to include the punctuation outside of the Branch's rules. Be careful that the sentence still makes sense grammatically if the optional Branch is skipped. Learn more about spacing in optional Branches.

Nesting Branches

What's the best Branching strategy for comparing two or more Data Variables at the same time?

❗️

Don't do this:

Ignoring ties for this simple example, the images below show how you could compare both halftime scores and finals scores for two teams by creating a separate rule for each combination. However, this method includes repeated logic that can be simplified.

👍

Do this:

Here, the repeated logic of home_halftime_score > away_halftime_score from rules 1 and 2 above is pulled out into its own Branch with the repeated logic of home_halftime_score < away_halftime_score from rules 3 and 4 above as the second rule. So the first Branch is just checking the halftime score, and then nested Branches within each of those rules check the logic for the final score. Clicking the Branch in rule 1 is shown as the second image below and clicking the Branch in rule 2 is shown as the third image.

Why? Nesting Branches in this way reduces logic repetition (fewer chances to make a typo) and makes logic easier to understand for others who may be working in the same Template. The parent Branch focuses solely on the halftime score first, and then the logic for the final score is nested within each rule.

Nested Branch Logic

How should I structure the logic in nested branches?

❗️

Don't do this:

Consider the example below where a clothing store has a true/false variable in its data for men's and women's clothes. The first image shows a rule checking for men's clothing. The nested Branch within that rule is shown in the second image, where the logic is checking for the type of clothing. However, it also has an unnecessary "mens" check for each rule as well.

👍

Do this:

Delete the unnecessary "mens" check in each of the rules of the nested Branch.

Why? Because the Branch is nested within the "mens" parent Branch, we know that "mens" has to be true to even evaluate the rules in the nested Branch. Therefore, we can remove that logic from each rule in the nested Branch.

❗️

Don't do this:

Don't include logic that will never evaluate as true in nested Branches. The first image shows the rule that goals > 0. Its nested Branch, shown in the second image below, has a third rule that contains the logic goals = 0. To evaluate the nested Branch, we know that goals > 0, so the goals = 0 rule is unnecessary.

👍

Do this:

Delete any unnecessary rules in nested Branches.

Why? While they won't break anything or evaluate as true, unnecessary rules can create confusion for others working on the Template, so they should be deleted.

Using Math Operators with Null Checks

How should I design around null checks when I need to perform math operations (addition, subtraction, multiplication, division) with those Data Variables?

❗️

Don't do this:

Don't include the null checks and math operators in the same rule.

👍

Do this:

First check for nulls in its own Branch. Then nest any math operators within that Branch, as shown in the second image below.

Why? Wordsmith evaluates rules as a whole, rather than piece by piece. If the null checks and math operators are in the same rule, rows that contain null values will error out when the content tries to run because Wordsmith can't perform math on null values. Nesting the Branches is any easy way to avoid this and arguably makes the logic easier to follow as well. Note this only applies to math operators, and not comparison operators (=, !=, >, >=, <, <=), which can be used in the same rule as null checks.

Spacing in Optional Branches

How do I make sure the spacing remains correct when I design optional Branches?

❗️

Don't do this:

As seen in the first image below, don't include static spaces before and after optional Branches, like the phrase "very good" below. If nothing evaluates as true in that Branch, you'll be left with a double space in your narrative. As seen in the second image, don't include a space after each rule within the Branch, since these can be hard to see.

👍

Do this:

Design the Branch so that it starts right up against the previous word in the sentence. Then, include spaces before each rule in the optional Branch, as shown in the second image below. If nothing evaluates as true for that Branch, the single space after the Branch will ensure the sentence remains grammatically correct.

Why? Putting spaces after each rule in an optional Branch is too hard for others to see and it's also easy to forget to add to each rule. Instead, we suggest putting the space before each rule.

The same concept applies to optional full sentences within a paragraph:

👍

Do this for optional full sentences:

Start the Branch right up against the period of the previous sentence. Then include spaces before each rule within the optional Branch.

Furthermore, utilize the same strategy when building entire paragraphs that are optional.

👍

Do this for optional paragraphs:

Note two line breaks are added in the text for this rule.

Why? If the spaces aren't added to the rule of the optional Branch, you'll have excess white space in your narrative when the optional paragraph doesn't hit for your rows of data.

Using "or" in Conditional Logic

Should I use "or" in the logic to combine rules or keep the rules separate? It depends!

📘

Using "or" to combine rules

The first image below shows how you can combine rules into one rule using "or." This is helpful if the associated text for each rules is very similar, so that it prevents you from rewriting the majority of the text. Instead, you can create a nested Branch just for the dynamic portion of the text. In the second image below, you can see how Wordsmith will select either "highest" or "lowest" depending on the data.

📘

Using separate rules

You can also keep the logic as two separate rules in the same Branch, as shown below. This is a good method to use if the associated text is structured differently. It's also slightly easier to follow since you don't have to navigate another layer deep to a nested Branch.

Try using both methods and see which one works best for you!

Combining the Title with the Lede

Often times, the title and the lede of a narrative will have the same logic. How should I design this?

❗️

Don't do this:

Don't create separate Branches for the title and lede that contain the same logic.

👍

Do this:

Put the text for both the title and the lede in the same Branch condition.

Why? Avoid repeating logic and text wherever you can. If you need to go back and change the logic, now you only need to change it in one place rather than multiple places. Don't be afraid to build large paragraphs inside of Branches if it makes sense to do so.

Using Shared Templates

When should I use Shared Templates?

📘

Recommendation: Reusing Branches for Synonyms

One good use of Shared Templates is when you are going to reuse the same Branch or Synonyms over and over again throughout your Template. The first image below shows a list of Synonyms that are converted to a Shared Template. In the second image, this Shared Template is inserted three times into another Template, as noted by the black dotted underline. The third image shows the narrative and how it randomly chooses a word from the list in all three places.

Why? If you are going to reuse a Branch or Synonym over and over again within a Template, it makes sense to convert it to a Shared Template rather than just copying and pasting it everywhere. That way, if you need to make changes, you only need to do so in one place and you don't need to worry about overlooking any places where that same Branch or Synonym is used.

📘

Recommendation: Easily reordering paragraphs

Another potential use case for Shared Templates is to easily reorder paragraphs within your narratives. Consider the example below, where Wordsmith is being used to create clothing descriptions. The first two images show separate Shared Templates for a color paragraph and a price paragraph. Inserting both of these into a Synonym of a third Template allows you to randomly change the order of the paragraphs. You can see the narrative in the fourth image below.

Why? Shared Templates are designed to make it easier to maintain pieces of your Template in one place. Anytime you might reuse the logic or text in a Template, it makes sense convert it into a Shared Template. Any changes only need to be made in one place and will be reflected any place where that Shared Template is being used.