// Title: Enhance usability of step by step instructions when step require using a CLI command
Requests
When we provide step by step instructions it is sometimes difficult to distinguish between the command itself and the unique variable or parameter we are requiring the user to input that is unique to their environment.
For example we have command block like this:
oc create -f f5-k8s-bigip-ctlr_openshift-node01-routes.yaml -f f5-k8s-bigip-ctlr_openshift-node02-routes.yaml
It would be helpful to have it something like this:
Or maybe even color coded where the variables are red.
In years past, when I would write deployment guides we would have a generic command that was set off from the rest of the text in the courier font, bolded and showed the command parameters setoff by greater than and less than signs.
I've tried to copy and paste an example here but the silly markdown styling converts the greater than and less than signs to something else. GRRR.
>big3d_install <IP address of target system >
One step further in some deployment guides is to do the above setting off command parameters in greater than less than and then to have a note which was to the effect:
In our example environment, we entered the following:
big3d_install 172.30.128.10
Environment
[ x] Cloud Foundry
[x ] Kubernetes
[x ] OpenShift
[x ] Mesos/Marathon)
Use Case
(i.e., what are you trying to do that you can't find documentation for?)
Here is an example from the BIG-IP docs on setting up DB variables. Is puts the greater than and less than variables for the command in a command block, then has a for example section directly underneath it.
// Title: Enhance usability of step by step instructions when step require using a CLI command
Requests
When we provide step by step instructions it is sometimes difficult to distinguish between the command itself and the unique variable or parameter we are requiring the user to input that is unique to their environment.
For example we have command block like this:
oc create -f f5-k8s-bigip-ctlr_openshift-node01-routes.yaml -f f5-k8s-bigip-ctlr_openshift-node02-routes.yaml
It would be helpful to have it something like this:
oc create -f f5-k8s-bigip-ctlr_openshift-node01-routes.yaml -f f5-k8s-bigip-ctlr_openshift-node02-routes.yaml
or like this:
oc create -f _f5-k8s-bigip-ctlropenshift-node01-routes.yaml -f _f5-k8s-bigip-ctlropenshift-node02-routes.yaml
Or maybe even color coded where the variables are red.
In years past, when I would write deployment guides we would have a generic command that was set off from the rest of the text in the courier font, bolded and showed the command parameters setoff by greater than and less than signs. I've tried to copy and paste an example here but the silly markdown styling converts the greater than and less than signs to something else. GRRR.
>
big3d_install <IP address of target system >
One step further in some deployment guides is to do the above setting off command parameters in greater than less than and then to have a note which was to the effect:
Environment
Use Case
(i.e., what are you trying to do that you can't find documentation for?)