Create use-case driven examples in the README

Have a question? Please checkout our Slack Community or visit our Slack Archive.

Describe the Feature

The README has a Wall of Text (WoT) which is overwhelming even for people who are familiar with the null label.

This prevents people from deliberately adopting (instead of accidentally adopting through usage of the open source modules) this module.

Expected Behavior

Real simple

module "label" {
  source  = "cloudposse/label/null"
  version = "0.25.0"

  # usually short name of org/company
  namespace = "org"

  # optional company tenant
  # tenant = "acme"

  # usually short/fixed name of region
  environment = "ue1"

  # usually short name of account
  stage = "prod"

  # usually the name of the root terraform module/dir/component
  name = "eks"

  # optional attributes
  # attributes = ["blue"]
}

# without tenant, module.label.id = "org-ue1-prod-eks"
# with tenant, module.label.id = "org-acme-ue1-prod-eks"
# without tenant and w/ attributes, module.label.id = "org-ue1-prod-eks-blue"
# with tenant and w/ attributes, module.label.id = "org-acme-ue1-prod-eks-blue"
output "label" {
  value = module.label
}

Running the above terraform shows you the full output of the module

There are other examples already (label2.tf) in the repo too which can be useful to figure out how to use this. However you'd have to dig here.

Use Case

This module is difficult to explain to users. I find myself going to the readme and then creating my own explanation or showing the users via an example like the one above.

Describe Ideal Solution

• Simplify the readme by making it less overwhelming
• Explain the inconsistent naming problem that it solves
• Explain how to use the null-label module
  • why is it called null-label instead of just label?
  • clearly what each common var means
  • what is generally used for each var and why?
  • how long should each of the vars be?
    • probably 5 or fewer characters
  • how to use it simply to get the identifier and tags?
    • see id and tags context
  • what is the context and what makes it so powerful?
    • anything that uses context.tf mixin can use the same identifier and override values
  • how to use it with other cloudposse modules?
    • can take advantage of context = module.label.contect to reuse names
• other use cases
  • how to use it for resources that require shorter names like target groups and LBs?
    • use id_length_limit or set one of the above inputs to null or "" to omit it from the id
  • how does cloudposse's amazing terraform framework tool known as atmos make use of this module ?
  • what if the labels need to be reordered?
  • what is the export context.tf and why should I use it in my terraform module?
  • how would I have the original null label inherit from another null label and override only one var like name?
  • when is it common to change the delimiter?
  • when is tags as list of maps useful?
  • etc

Alternatives Considered

I write a blogpost on this or someone else does to help explain everything

Additional Context

N/A

Start by reading the current README and the existing examples in examples/complete, especially label2.tf, to understand the module’s documented usage. Restructure the README around use cases and add examples covering common variables, IDs and tags, context reuse, length limits, and related modules. Done means users can understand the naming problem and follow focused examples without digging through the repository.