Create use-case driven examples in the README

[nitrocode]

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

[natemccurdy]

Another thing that might help adoption: explaining, with examples, what problem this module is meant to solve.

I recently found this module because it was used by other CloudPosse modules. As I read the readme, I realized that I didn't really understand why I'd want to use this module. And the wall of text you mentioned further muddied the waters... so I stopped reading.

Are there any real-world examples of folks using the module to go from <example_of_poorly_named_resources> to <example_of_well_named_resources>?
People might not even realize they're poorly naming things until they see an example of code that they recognize as their own.

Anyway, just my 2 cents as someone recently discovering this module and wondering if I should use it. Thanks for making these modules 🍻

[nitrocode]

@natemccurdy I completely agree. I added some use-cases above after your comment that might help explain it a little more.

[nitrocode]

cc: @Gowiem posted this https://masterpoint.io/updates/terraform-null-label/