[Content Suggestion] FOCUS line item examples

[AWS-ZachErdman]

Description

There are a few columns in which readers may interpret the column definition in different ways. This could cause cloud providers to populate columns differently or for cloud consumers to interpret values incorrectly.   Can the specification consider adding line item examples for all columns for a generic cloud provider and for a few common scenarios? Some scenarios include: commitments, discounts, and unused commitment.

As one example, we felt it was ambiguous for an Unused Commitment line item what data should be in columns like PricingQuantity, ListCost, etc. We'd like to make clear what the best practice is for populating all columns for the common scenarios to reduce the likelihood that any cloud vendor needs to make changes to their FOCUS dataset to match other vendors.

Proposed approach

We propose writing up some examples of full line items into the spec. It would be valuable to include some of these directly in the spec, rather than in the supporting content section which can be easily missed.

Github issue or Reference

N/A

Context

N/A

[flanakin]

I like this idea. We could introduce a fictitious provider or maybe a couple different types of providers to support this. Let's just make sure the example values are natural language using simple, straightforward terms and not codified in any way. We don't want a secret decoder ring to understand what the fictitious service names are.

That said, it shouldn't be required to understand the spec. In the examples you call out, we should just make sure each of those columns explicitly calls out how unused commitment rows should be handled. That should also be explicitly detailed out in the Discount handling attribute, but the column specs are the primary source of truth for how to handle all scenarios for that column.

[AWS-ZachErdman]

I like this idea. We could introduce a fictitious provider or maybe a couple different types of providers to support this. Let's just make sure the example values are natural language using simple, straightforward terms and not codified in any way. We don't want a secret decoder ring to understand what the fictitious service names are.

That said, it shouldn't be required to understand the spec. In the examples you call out, we should just make sure each of those columns explicitly calls out how unused commitment rows should be handled. That should also be explicitly detailed out in the Discount handling attribute, but the column specs are the primary source of truth for how to handle all scenarios for that column.

@flanakin I like the idea that you don't need the examples to understand the spec. Im trying to imagine how to modify the column descriptions to be all inclusive though. In order for that to work, would we need to specify for every column how it should appear for all charge types (e.g., usage vs. commitment vs. unused commitment vs. refund)?

[udam-f2]

Not going in the spec.. do after freeze period for v1.0.