Docs: placeholder text in terminal commands can be confusing
Problem to solve
We have many cases where we need to display some placeholder text in a command. For example, an email, a username, a token, etc.
So far, we've been using the notation <your_email>
, <your_username>
, <your_access_token>
. Sometimes, we use a fake value, but we have kinda standardized with <your_something>
.
While this is much better than using a fake value, the special characters <>
can be confusing to a user, are they part of the command or no? We should do something to clarify this.
Proposal
Use simple text with no special symbols, like the DigitalOcean guide https://www.digitalocean.com/docs/style/language/#stand-in-variables.
Use
use_your_<variable>
with in-line code formatting when indicating when the user should substitute their own value in a command. For example,use_your_droplet_ip
oruse_your_domain
.