Socket Slack Docs

[yllek]

Description

Feedback from a user in Install Botkube in K8s Cluster section of Socket Slack docs:

Inputting the cluster name and other exported variables with curly brackets ({cluster_name}) will cause errors when running the following lines of config settings.

For example:
export CLUSTER_NAME={example_cluster}
will result in:
--set settings.clusterName=${{example_cluster}} \

and will throw an error. It is difficult to debug as the error message isn't descriptive.

Expected behavior

export CLUSTER_NAME=example_cluster
will result in:
--set settings.clusterName=${example_cluster} \

Actual behavior

export CLUSTER_NAME={example_cluster}
will result in:
--set settings.clusterName=${{example_cluster}} \

Steps to reproduce

I have not tried to reproduce myself. If docs are incorrect, remove curly bracket around value example. If docs are correct, then more clarity or a call out for users who might overlook.

[pkosiec]

Hi @yllek, thank you for posting the user feedback.

We use single curly braces to show that a given text is a placeholder. So, in case of export CLUSTER_NAME={cluster_name} we expect that users will replace {cluster_name} with some text, like:

export CLUSTER_NAME=example_cluster

So curly braces should we always removed in such cases.

However, I agree this might be confusing as we don't state it anywhere clearly that curly braces is our way to define placeholder. We tried to follow the MS content guidelines: https://learn.microsoft.com/en-us/contribute/content/text-formatting-guidelines#placeholders, but we clearly lack the "Inform the reader about the placeholder" guideline.

Should we add text like "Text in curly braces, such as {cluster_name} is a placeholder, and should be replaced fully with your value" or something like this? Or can we have a single place where we define the basic content rules? 🤔