F5Networks / f5-ci-docs

Documentation for F5's Container Ingress Services
http://clouddocs.f5.com/containers/v2
Apache License 2.0
7 stars 27 forks source link

Enhance usability of step by step instructions when step require using a CLI command #361

Open pdp2shirts opened 6 years ago

pdp2shirts commented 6 years ago

// 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:

In our example environment, we entered the following: big3d_install 172.30.128.10

Environment

Use Case

(i.e., what are you trying to do that you can't find documentation for?)

pdp2shirts commented 6 years ago

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.

https://support.f5.com/csp/article/K16953