Advanced: Data Style Guide
Click to see other available Wordsmith style guides
Spacing in Data Variable Names
How should I use spacing in my Data Variable names?
Don't do this:
The example Data Variable below is hard to read and understand.
Do this:
Wordsmith won't allow you to use spaces within your Data Variables' names, but it's a best practice to use underscores instead. The Data Variable name listed below is now easier to read and interpret.
Why? Data Variable names should be clear, since they'll be used over and over again in your Template.
Descriptive Data Variable Names
How descriptive should my Data Variable names be?
Don't do this:
Data Variable names should be clear, not ambiguous.
Do this:
Be as descriptive and specific as you can be when naming variables within your data.
Why? Try to balance Data Variable names between being long and descriptive and short in length. Ideally, these should be as short and descriptive as possible.
Symbols in Data
Should I leave symbols in my data or take them out?
Recommendation:
Either way should work in Wordsmith. Even with symbols in the data, Wordsmith will still allow you to perform comparisons and math on those Data Variables. Wordsmith also offers various formatting options within the editor so you can display your data the correct way.
Building Formulas in Wordsmith
When should I build a formula in Wordsmith?
Do this:
Wordsmith allows you to do some data manipulation in the editor, but only using the existing columns in your data. Therefore, you can create calculations across columns, but not across rows. In the example below, we have sales and sales_last_month in our data csv. Using those columns, we can create formulas for percentage change and difference between the two months. In the third image below, you can see how inputting those new calculations can help add variability to our narrative.
Creating True/False Formulas
How can I create a shorthand for complicated logic?
Do this:
In the example below, let's say we have current sales and three other sales figures: last's month value, the year-to-date average, and the quarter average. We want to compare the current sales value to the other three, but don't want to show all that complicated logic in the rules of a branch because it's too confusing. The second image below shows how you can create a true/false formula and give it a friendly name. Maybe 'great_month' means the current sales value was greater than all of the other three benchmarks. You can create other true/false values for situations where a month wasn't so good. Then, as shown in the third image below, you can use those friendly names in the rules of your branch rather than the huge block of complicated logic. It's easier to understand and manage this way. Plus, if you decide to change what it means to be a 'great_month', you only need to make the change in one place.
Using Data to QA Your Template
How can I change my data to help me QA my Template?
Recommendation:
Wordsmith will let you preview the first 50 narratives from your Template. If the first 50 rows of your data is sorted in some way, you may not be seeing much variation from your Template. You could try uploading a different data set with a random sample in the first 50 rows to get a better idea of how much variation your Template has. Another way to change your data to help you QA is to find or create a row of data that will evaluate as true for each rule in your Template. That way, you can verify you've seen all possible outcomes from your Template.
Get the Most Out of Your Data
What can I add to my data set to make better narratives?
Recommendation:
While every use case is different, a general rule of thumb is the more data, the better! Any additional fields will give you more options to be able to differentiate rows from each other, tell different narratives, and add more variability. We've found that in addition to raw data values, historical data, streaks, ranks, and averages are all good things to add if you can. You won't be able to calculate these in Wordsmith using formulas, so they'll need to be added directly to your data set. In the example below, you can see we've ranked sectors and added streaks for each fund for a financial report. These will not only help in making the Template easier to design, but will enrich the quality of the narratives too.
Updated over 4 years ago