docs: initial updates to state timeline documentation

[mdcruz]

What is this feature?

Updates to the state timeline docs to include:

• how to configure a state timeline (to be added as a video)
• supported data formats and example
• when to use a state timeline

Why do we need this feature?

To explain to our users how to configure a state timeline easily and when to use it.

Who is this feature for?

Grafana OSS and Cloud users

Which issue(s) does this PR fix?:

Fixes #

Special notes for your reviewer:

Please check that:

• It works as expected from a user's perspective.
• If this is a pre-GA feature, it is behind a feature toggle.
• The docs are updated, and if this is a notable improvement, it's added to our What's New doc.

[leeoniya]

for the data format, each state ends when the next state begins or when there is a null value.

we very recently added support for a second time field that can be used to indicate state endings, because null values (or "no data" states) can be difficult to insert using our transforms or query changes. (#84130)

[leeoniya]

this is the first time i've seen the term "state regions". it may be confusing because this panel also supports region annotations. this is not a request to change the terminology, just a comment. i dont have a better name for them 😅

"horizontal bands" may alternatively be called "lanes"

[imatwawana]

The "state regions" terminology exists in these docs all the way back to when this visualization was introduced in v8.0. I'm thinking since it's been here all this time, it would be more confusing to change it at this point unless we get significant feedback that it's confusing.

[imatwawana]

The more I stare at the words "horizontal" and "length", the more I wonder if these are the correct words here. If we're talking about something we're measuring from left to right in a two-dimensional context, then that's really a "width" (like the way we'd refer to H and W of an image to control it's size). I've suggested removing the word "horizontal" entirely in my edit below because I don't think it's necessarily adding anything in terms of meaning.

If "length" makes sense to everyone else, I'm not intent on changing it; it just struck me as odd.

[leeoniya]

yeah, it can be either, really. "length in time", and "width in pixels"

[imatwawana]

This is a great start, @mdcruz! This really helps clarify why you'd want to use a state timeline and what kind of data you need to use one. I'll review this again once you've put the video in so I can just make sure the balance of the page still looks good and to catch any copy edits I missed on this review.

[imatwawana]

The more I stare at the words "horizontal" and "length", the more I wonder if these are the correct words here. If we're talking about something we're measuring from left to right in a two-dimensional context, then that's really a "width" (like the way we'd refer to H and W of an image to control it's size). I've suggested removing the word "horizontal" entirely in my edit below because I don't think it's necessarily adding anything in terms of meaning.

If "length" makes sense to everyone else, I'm not intent on changing it; it just struck me as odd.

[mdcruz]

for the data format, each state ends when the next state begins or when there is a null value.

we very recently added support for a second time field that can be used to indicate state endings, because null values (or "no data" states) can be difficult to insert using our transforms or query changes. (#84130)

Thank you, @leeoniya! I'll add this to the docs :)

[mdcruz]

@imatwawana I've added another state timeline example to show two time columns without null values, to reflect the latest changes that @leeoniya worked on here: #84130

[imatwawana]

@imatwawana I've added another state timeline example to show two time columns without null values, to reflect the latest changes that @leeoniya worked on here: #84130

Looks great!

[imatwawana]

Let's chat about this addition. We don't want to be repeating what is a fairly simple process (creating a visualization) over and over in the docs. We have docs that explain how to add visualizations that we can point folks to. Is the focus here the transformation?

[mdcruz]

@imatwawana Can you point me to that doc explaining how to add visualization? I can link that instead. For the transformation, I have covered this as part of the video so we can remove it.

[imatwawana]

Create a dashboard describes how to create a dashboard including adding a visualization and a data source.

[imatwawana]

Awesome!

[grafana-delivery-bot]

This PR must be merged before a backport PR will be created.

[grafana-delivery-bot]

This PR must be merged before a backport PR will be created.

[grafana-delivery-bot]

This PR must be merged before a backport PR will be created.