Add a walkthrough of an actual graph example to explain content

[estherk15]

What does this PR do? What is the motivation?

• Adds an example through graphs of what users are seeing
• This supplements the existing content of the guide
• Editorial review: https://datadoghq.atlassian.net/browse/DOCS-11272

Merge instructions

Merge readiness:

• Ready for merge

[github-actions]

📝 Documentation Team Review Required

This pull request requires approval from the @DataDog/documentation team before it can be merged.

Please ensure your changes follow our documentation guidelines and wait for a team member to review and approve your changes.

[github-actions]

Preview links (active after the build_preview check completes)

Modified Files

• https://docs-staging.datadoghq.com/esther/docs-update-rollup-guide/dashboards/functions/rollup
• https://docs-staging.datadoghq.com/esther/docs-update-rollup-guide/dashboards/guide/rollup-cardinality-visualizations

[cswatt]

Sorry for this annoying review! I started out understanding it and began to get confused—I think I need to see an equation for the computations here.

[cswatt]

Suggested change

	### Unique vs Distinct Users
	### Unique versus distinct users

[cswatt]

Suggested change

	### How Rollup Affects Averages
	### How rollup affects averages

[cswatt]

Seems like this paragraph should be moved up a section, as it pertains to unique vs distinct users

[cswatt]

I think most users are coming to this page with an idea of what the rollup function is, but in case they don't, let's link "rollup function" to https://docs.datadoghq.com/dashboards/functions/rollup

[cswatt]

Suggested change

	1. **Smoothing Effect**:
	- Longer time periods (30-minute rollups) create smoother graphs.
	- Shorter time periods (5-minute rollups) show more detailed spikes and variations.
	2. **Average Calculations**:
	- In shorter time periods, averages might be lower as we only catch users in that exact moment.
	- In longer time periods, averages might be higher as we catch more instances of users using different devices.
	- This isn't a bug, it's a natural result of how users interact with your service over time.
	- **Smoothing effect**:
	- Shorter time periods (5-minute rollups) show more detailed spikes and variations.
	- Longer time periods (30-minute rollups) create smoother graphs.
	- **Average calculations**:
	- In shorter time periods, averages might be lower because Datadog only catches users in that exact moment.
	- In longer time periods, averages might be higher because Datadog catches more instances of users using different devices.

the suggestions I've made:

• Changed from an ordered list to an unordered list. There isn't a hierarchy between smoothing effect and average calculations, they're just both items at the same level.
• Sentence-case for both "Smoothing effect" and "Average calculations"
• Under "Smoothing effect," switched the order of the two bullet points. This matches the order under "Average calculations," and intuitively, short time periods come before long time periods
• Removed that last bullet point, seems a bit odd and unnecessary

[cswatt]

Suggested change

	{{< img src="/dashboards/guide/rollup-cardinality-visualizations/users_mobile_rollup_5_30min.png" alt="Users mobile rollup comparison between 5 and 30 minute intervals" style="width:100%;" >}}
	{{< img src="/dashboards/guide/rollup-cardinality-visualizations/users_mobile_rollup_5_30min.png" alt="Line graph displaying percentage of users on mobile rolled up every 5 minutes (blue line) compared to 30 minutes (purple line). The smooth purple line is higher than the spiky blue line." style="width:100%;" >}}

[cswatt]

Suggested change

Looking at the individual graphs, you'll see the numbers align in the following way. The 30-minute rollups are, of course, larger than the 5-minute rollups. When you scale them down by a factor of 0.75, the total number of distinct users roughly aligns with the 5-minute rollup, while the number of mobile distinct users is significantly higher. Why?

The following graph looks at 5-minute versus 30-minute rollups for mobile distinct users and total distinct users. Because the 30-minute rollups are naturally larger than the 5-minute rollups, this graph displays the 30-minute rollups scaled down by a factor of 0.75. For total distinct users, the 5-minute and 30-minute rollups roughly align. However, for mobile distinct users, the 30-minute rollup is significantly higher than the 5-minute rollup. Why?

was struggling to understand this paragraph, so rewrote it

[cswatt]

Suggested change

	{{< img src="/dashboards/guide/rollup-cardinality-visualizations/total_users_scaled.png" alt="Scaled rollup comparison showing distinct users" style="width:100%;" >}}
	{{< img src="/dashboards/guide/rollup-cardinality-visualizations/total_users_scaled.png" alt="Line graph showing four lines: total distinct users (5-minute rollup), total distinct users (30-minute rollup), mobile distinct users (5-minute rollup), mobile distinct users (30-minute rollup)." style="width:100%;" >}}

More alt text. Less descriptive this time because the interactions of the lines are explained in the text

[cswatt]

Suggested change

This occurs because when a user appears multiple times during a rollup window, they appear once in the denominator but multiple times in the numerator. In this case, a user may be using both mobile and desktop. The following graph shows two offset graphs for a single user. The bottom graph indicates whether the user appeared on mobile during the 30-second or 5-minute interval, while the top graph indicates whether the user appeared at all.

This occurs because when a user appears multiple times during a rollup window, they appear once in the denominator but multiple times in the numerator. In this case, a user may be using both mobile and desktop. The following visualization shows two offset graphs for a single user. The top graph indicates whether the user appeared at all, while the bottom graph indicates whether the user appeared on mobile.

edits:

• changed "graph" to "visualization". this is nitpicky, i just don't like the phrase "the graph shows two graphs"
• re-ordered clauses in the last sentence. english readers scan top to bottom, left to right. the top graph should be explained before the bottom graph.

---

But I'm also having some trouble understanding the first sentence, about the user appearing once in the denominator and multiple times in the numerator. Why is there a numerator and a denominator, what are we calculating, what does the numerator represent, what does the denominator represent?

I'm guessing that we are calculating average percent of total users on mobile? I think it would help me, at least, to see what this equation actually is.

[cswatt]

haha so after looking at the notebook, I'm understanding this more. Let's write out the equation cardinality:@usr.name[@type:session @device.type:Mobile] / cardinality:@usr.name[@type:session] * 100, and make it clear that this is the numerator/denominator we're talking about

[cswatt]

I can't parse this statement. The user appeared only occasionally on mobile, so they appear more often on mobile?

[cswatt]

Forgot this note about the graphics. Let's clone/edit the notebook and then take new screenshots:

• it's really not obvious what each colored line represents, and the displayed key is useless. Let's add aliases to the lines, so each graphic has an informative key that says the blue line is 5-min rollup, the purple line is 30-min rollup, etc.
• These are not fractions—they're percentages! Let's replace "Fraction" in each graph title with "Percentage"
• For the last two graphs, it's kind of hard to tell the color difference between the blues. I know it's the classic color palette, but it doesn't make much sense for two groups of two lines, where we're trying to emphasize a difference in mobile vs. total. Maybe we can keep the blue/purple for mobile, and then do a red/yellow for total.