Closed tylerkelly13 closed 3 years ago
++1
+1
What do you suggest?
I suggest using <variable> to make the replaceable more obvious to the user. this is the convention used in openshift docs, as well as some middleware products
@tylerkelly13 by that you mean mandating the enclosing of the value in <>
?
Yes, it helps replaceable code stand out more for the user. Some of our code (possibly most) can be copied and pasted from our docs into a terminal and run without modification. It's important emphasize code that needs modification before being run.
Using <> around a replaceable would be double markup when using italics. Leave them for manual pages.
Re: configuration parameter or environment variable
I agree they should not be in italics. If these are in capitals, such as directives, then no markup is required, but no strong objection to `` for these.
I have been using `` for commands as we already use ** for GUI labels.
Closing this issue as the replaceable value guidance has been evaluated by the supplementary style guide project, and the effort to update this guide is being handled in #36.
Use of Italics for "System or software variable to be replaced by the user" and "System or software configuration parameter or environment variable" may lead to confusion.
Recommend reviewing this convention.