An example of command line interface documentation can be found with IBM Rational's ClearCase(going waaaay back in the day) commands that can be used for inspiration on how to improve our documentation:
Feedback from Daniel:
I am loving the ability to set the Telepresence intercept ingress parameters via the command line (perfect for scripting dev environment setups :awesome:), and wanted to share a piece of docs/help feedback. I initially scanned telepresence intercept --help , saw the flags and crafted this command based on my previous experience of answering the questions that pop up in the terminal (edited)
% telepresence intercept web-app-57bc7c4959 --service web-app --port 8083:80 --ingress-port 80 --ingress-tls n --ingress-host ambassador.ambassador --ingress-l5 ambassador.ambassador
Using ReplicaSet web-app-57bc7c4959
intercepted
Intercept name : web-app-57bc7c4959
State : ACTIVE
Workload kind : ReplicaSet
Destination : 127.0.0.1:8083
Service Port Identifier: 80
Intercepting : HTTP requests that match all headers:
'x-telepresence-intercept-id: e54b9e4c-7f24-4a66-b15a-e47a8f9e3990:web-app-57bc7c4959'
Preview URL : https://pedantic-taussig-1895.preview.edgestack.me
Layer 5 Hostname : ambassador.ambassador
telepresence: error: n: exec: "n": executable file not found in $PATH
If you think you have encountered a bug, please run `telepresence gather-logs` and attach the telepresence_logs.zip to your github issue or create a new one: https://github.com/telepresenceio/telepresence/issues/new?template=Bug_report.md .
Because the command returned a non-successful exit code my script failed and Telepresence quit
A quick bit of trial and error (and also re-reading the help a bit more closely) revealed that --ingress-tls is actually a flag that requires no value to be set :slightly_smiling_face: I wonder if other part-time/distracted developers like myself who have become used to answering the ingress questions (almost robotically) on the terminal may stumble into the same issue? (cc @Eric Funk) (edited)
And following this thought, I wonder if including some example values in the help docs would be useful, especially for the host and l5 e.g. "ambassador.ambassador"
We should enhance the https://www.telepresence.io/docs/latest/reference/client page to provide more information on each command equivalent (or better to what the --help option would provide for each command):
An example of command line interface documentation can be found with IBM Rational's ClearCase(going waaaay back in the day) commands that can be used for inspiration on how to improve our documentation:
Feedback from Daniel: I am loving the ability to set the Telepresence intercept ingress parameters via the command line (perfect for scripting dev environment setups :awesome:), and wanted to share a piece of docs/help feedback. I initially scanned telepresence intercept --help , saw the flags and crafted this command based on my previous experience of answering the questions that pop up in the terminal (edited)
Because the command returned a non-successful exit code my script failed and Telepresence quit
A quick bit of trial and error (and also re-reading the help a bit more closely) revealed that --ingress-tls is actually a flag that requires no value to be set :slightly_smiling_face: I wonder if other part-time/distracted developers like myself who have become used to answering the ingress questions (almost robotically) on the terminal may stumble into the same issue? (cc @Eric Funk) (edited)
And following this thought, I wonder if including some example values in the help docs would be useful, especially for the host and l5 e.g. "ambassador.ambassador"