What to Write Using Branches

Branches allow you to change what's written in your stories based on different scenarios in your data, which means they allow you to do a lot of different things: specifically describe your data, prioritize the information you talk about, surface what's relevant to your audience, and draw comparisons from multiple data variables.

Specifically describe your data

Branches allow you to specifically describe your data, and because of that, they are also a great way to add variability to your text. The more specific each narrative is, the more it will differ from other narratives.

Go beyond Branches that just indicate an increase or decrease by adding more rules for different scenarios. For example, you can write a rule for a scenario in which revenue increased more than 50% over the previous period. Keep in mind that Branches in Wordsmith adhere to the waterfall method - each rule is evaluated from the top-down, so structure your Branch to include the rarest rules at the top.

In this Branch, the phrase will be customized depending on the size of the percentage change: if it is above 50%, between 25% and 50%, and if it is between 0% and 25%.

You can also change an adjective describing a specific scenario.

In this weather forecast, the adjective before the high temperature will change depending on how hot or cool it is.

Lead your narrative with the most relevant information first

With Branches, you can structure your narrative to discuss topics based on their statistical significance or importance. The lede of a narrative is one of the most important sentences or paragraphs because it's what your audience is going to read first, and it sets the tone of your entire narrative. You can use Branches to change the topic of the lede for different scenarios in your data.

Think about how important each topic is and what makes it important to your readers. That priority will become your Branch. For example, in a Quarterly Earnings Report, you may want to talk about a company's performance against its benchmark if it is significantly over or under that benchmark. Then the next most important topic is net income, and how the company performed against market estimates. If neither of those are statistically significant, then you want to talk about the revenue if it is much higher or lower than the estimate.

Only write about topics that are interesting to your audience

You can think about some Branches as optional, meaning there are only certain scenarios that you want them to be written and otherwise you don't want anything written. These Branches won't have the default rule you can use by clicking the "add text if no rules are true".

You can use optional Branches to only discuss a particular topic if the data about that topic is interesting, has changed in a significant way, or other statistically significant thresholds are met.

In the example of a Credit Card Statement Summary, you may only want to write about top or bottom spending category if the category increased or decreased significantly. If it just rose or fell a small amount, it's not that interesting and you won't write about it.

These sentences will only be written if the top spending category rose more than 10% this month or the bottom spending category fell more than 10%.

Or you can include a clarifying phrase or additional detail to a sentence based on a scenario in your data.

In this Quarterly Fund Report, we will write about a positive or negative streak in a company's returns only if there have been consecutive periods that performed the same.

Mastering how to effectively create optional Branches will increase your narrative’s variability, sophistication, and ability to call out interesting insights when they occur. You can communicate only the information relevant to your audience and provide more variability in what you're writing. You'll only be talking about some topics if certain data scenarios are met, making your narratives more specific to that particular scenario (and likely more unique compared to other scenarios). You'll also change up what sentences and phrases are included in your narratives, making the length of your narratives and the topics included in them change from narrative to narrative.

Compare multiple data points at a time

As a writer, you likely evaluate a couple different data points and describe something specific about those two (or more) metrics. You can also do that with Branches by either using "and" and "or" in your Branch rules or nesting Branches inside each other. This way, you can draw correlations, reference trends, or highlight uncommon outcomes in your data, just like you would if you were writing each narrative by hand.

In the weather forecast, the first rule describes conditions where the morning, afternoon, and evening differs from each another. The second rule describes sunny conditions all day. And the third rule describes the possibility of snow in the morning, afternoon, or in the evening.

You can also nest Branches as a way to compound your logic and reference multiple data variables. The child Branch rule is only true if the Parent rule is also true, so it's the same as using "and" in one rule.

Call out extraordinary scenarios in your data

Use Branches to account for data scenarios that are outside of the norm. For example, if the stock price today is the highest it's been in 52 weeks, that's a notable event that you should write about in your narrative.

Think through outlier scenarios that could happen in your data and make sure you include those in your Branches. And remember to structure your Branch with the most rare rules at the top!

Mimic random variability using the modulo function

The modulo function finds the remainder of division after one number by another. You can manufacture random variability by adding a sentence or phrase in every other narrative. If you have a unique identifying number in your data (like SKU), use modulo to write a sentence only when the identifying number is an even number. This will add a layer of variability in addition to the random variations from Synonyms.

This sentence will only be written if it's SKU is an even number.

Create a list of data points

You may want to evaluate multiple data variables and reference them in your narrative only if they meet certain criteria. You can use a nested Branch structure to list these data variables or insights in the same sentence or phrase.

For example, if we're describing different TVs, we may want to write a sentence about up to 3 different features that each TV could have: 3D capability, Wifi, and if there are more than one HDMI ports. Each TV is unique and could have any combination of these 3 features, which means there are 7 possible scenarios or combinations of these features, visualized by the grid below.

To set up the nested Branch to capture all of these possible scenarios, let's start with Scenario 1 (the TV has 3D capabilities, Wifi, and more than 1 HDMI ports). Check for 3D capabilities in the first rule of a Branch, then create a nested Branch inside that rule to check for Wifi, then create a nested Branch inside that rule for HDMI ports. The logic from the parent Branches is compounded with the nested Branches, so that by the time you get to the end of that 3rd level, you've created an option for this: 3D is TRUE and wifi is TRUE and hdmi_ports > 1. Now you can write a phrase specific to that scenario.

These Branch rules are actually nested inside each other. The blue text indicates that that phrase is a Branch. Since we know that in order to get to the third level of the Branch, all the parent rules had to be true, this scenario has 3D capabilities, Wifi, and multiple HDMI ports.

Use the "Add text if no rules are true" default rule to account for the alternative scenario if there are not more than one HDMI ports. Since you're still in the third level of the Branch, you know the rules from the parent Branches are true, so you know that 3D is true and Wifi is true, but hdmi_port > 1 is false (scenario 2 from the grid).

We can write that the TV has 3D capabilities and Wifi because we know that the rules from the parent Branches has to be true.

Now that we've built the first two scenarios for the third level of the Branch, let's go up a level to the second level. This is the Branch where we checked for the TV having Wifi. But we should also add an option for if the TV doesn't have Wifi, but does have more than one HDMI ports (scenario 3 from the grid). So the second rule in this Branch should be checking for HDMI ports.

The rule for the parent Branch is that the TV has 3D capabilities. So we know that the TV has 3D, does not have Wifi, and does have more than one HDMI ports.

And finally, we need an option for if the TV doesn't have Wifi or HDMI ports, but does have 3D capabilities (scenario 4). So we can use the default rule for just 3D capabilities.

The rule for the parent Branch is that the TV has 3D capabilities. And the text in the default rule is only written if the rules in that Branch are false. So we know that 3D is true, Wifi is false, and hdmi_ports > 1 is false.

Now we still need to account for scenarios 5, 6, and 7, so let's go back to the first level of the Branch. We've written an option for every scenario where the TV has 3D, but now we should add options for the TV not having 3D, but having some of the other features. If the TV doesn't have 3D, let's check to see if it has Wifi. Write a rule for Wifi, and then add a nested Branch to check for HDMI ports.This is scenario 5 from the grid.

In order to get to this second level of the Branch, we know that the TV does not have 3D (because that had to be false in order for the second rule to be evaluated), the TV does have Wifi, and the TV had more than one HDMI ports.

And we need to add an option if the TV does not have more than one HDMI ports, but does have Wifi (scenario 6). So we'll use the default rule.

We know in this scenario that the rule from the parent Branch is true, so the TV has Wifi. And we know that the first rule in this Branch is false, so the TV does not have more than one HDMI ports.

To account for scenario 7, which is a TV with just more than one HDMI ports, we'll create a third rule in the first level of the Branch.

In order to get down to rule 3, we know that the first two rules had to be false. So we know that the TV does not have 3D capabilities, does not have Wifi, and does have more than one HDMI ports.