Should we prefer dot notation for object settings?

[pnadolny13]

This conversation was started in this PR but I wanted to pull it out to discuss further and get more thoughts.

Like @edgarrmondragon pointed out we can flatten an object setting into its individual elements using dot notation. The pros are that it simplifies the UX when setting them and also allows you to set individual elements with environment variables (see this comment for Edgar's explanation). The down side is that its sometimes very verbose i.e. the tap-nice-incontact example since the settings are 1-1 with a stream and definitions need to be redefined in each setting.

The plugin definitions today are a bit of a mix so would be good to decide on patterns:

1. Should we prefer dot notation when possible?
2. When should we chose to set the top level object key and list the contents in the description instead?
3. Should we put these rules of thumb in the plugin definition syntax docs or maybe better in the CONTRIBUTING docs in the hub? Then the recommendations are easier to keep consistent and we dont need to re-hash best practices in PRs as much

[tayloramurphy]

My long term preference would be to improve setting definitions so that we can capture this complexity with having to sacrifice the UX.

If a setting has sub-settings, we should just be able to define that as we normally would a setting, and then in interactive CLI and the eventual UI we could render and ask for the data properly. Folks could still use the dot notation or the environment variables and interactive could be updated to traverse the tree properly.

  kind: object # maybe we need a new type here?
  label: Periods
  name: periods
  subsettings: # not a fan of subsettings but you get the idea
  - name: contacts_completed
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: skills_summary
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: skills_sla_summary
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: teams_performance_total
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: wfm_skills_contacts
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: wfm_skills_dialer_contacts
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: wfm_skills_agent_performance
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: wfm_agents
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: wfm_agents_schedule_adherence
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes
  - name: wfm_agents_scorecards
    kind: options
    options:
    - label: Days
      value: days
    - label: Hours
      value: hours
    - label: Minutes
      value: minutes

[edgarrmondragon]

The Hub or a future UI could already group split the setting names and group them based on prefixes. For example periods.skills_summary and periods.skills_sla_summary could be processed under the hood as a tree:

periods
├── skills_summary
└── skills_sla_summary

[tayloramurphy]

True - I wonder though if that's where we'd want to put the complexity. Having easy to use metadata in the YAML is essential since folks will be manually updating it quite a bit.