Introduce real-world examples and contexts for OpenSLO spec, definitions, features, etc.

[programmer04]

Problem to solve

Some features of the spec introduce some more sophisticated features. Those without additional context may not be understood correctly by newbies or seems odd (e.g. taking a list as an input instead of a single item).

They aren't aware of how common the use case it is in a real-world scenario for a particular feature that is obvious for veterans in defining SLOs. For instance, having multiple objectives in one SLO is pretty common - tighter for internal use and looser for external use. Or defining multiple time windows - shorter for quick, internal feedback for teams, and longer for external use. There are countless examples like that.

By having them documented somewhere we also spread more awareness and educate people about SLO.

Proposal

Plenty of repositories have folder examples where such stuff is put. We should put heavily commented YAMLs that represent real-world scenarios. Also, additional text that describes more details, context, use cases, etc. Referencing literature e.g. SRE Books that are available online and acclaimed would be great too.

Next, we should link to them from the main page of the spec when more complicated features are specified. For instance by putting something like that

To learn more about use-case for this feature check [link-to-specifc-doc-from-example-dir].

Some minimal examples that use only basic features can be included in this example dir too.

[fearfactor3]

I can start adding some of the real-world examples that we use and modify them for the example dir.

[programmer04]

It's a great idea @fearfactor3! Please remember to add some short note for your definitions that answers the questions

• What are you measuring?
• Why are you measuring this?
• How it helps with providing a reliable platform to end users?
• Whatever seems right for you 🙂

I think it'll educate people and help with better understanding because we don't want to have a steep learning curve with SLOs.

What do you think?

[programmer04]

I think the scope of this issue contains what you proposed in #40 @ian-bartholomew could we close it to avoid duplication?

[fearfactor3]

@fpiwowarczyk - I've looked at your example and I like how you set it up. Do you mind if use your template for what I plan to do with this?

[fpiwowarczyk]

@fearfactor3 no problem at all :) we can say it is opensource :D