-
Notifications
You must be signed in to change notification settings - Fork 30
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Updates to support writer's guide changes + placeholders nuance #35
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Basically, LGTM 👍 I've only looked at the text for placeholders.
(I guess it's possible we may think of other exceptions to the default placeholder rule later, but we can update the placeholder section if we do)
|
||
For example, `{PORT}`. | ||
|
||
== Other Placeholders |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is it worth emphasizing that this is the default formatting for placeholders?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't know about "default" - I think I'd rather just leave it as "other" - since we want the other two options to be used where appropriate, first.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A slight surprise to see using all caps for the URI placeholders. But it does make it consistent across all of the placeholder types and also is in line with Google's standards.
When you need to add a placeholder value to a xref:examples.adoc[code example]: | ||
The type of placeholder you add to code depends on the type of xref:examples.adoc[code example] you're including. | ||
|
||
== curl and Shell Placeholders |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cURL
(throughout)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I was surprised to find out recently that they've renamed cURL to curl.
Had to change it in a few places in the docs.
|
||
== Other Placeholders | ||
|
||
If your code format does not support a value using curly braces (`{}`) or a `$` prefix, then you must: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
...for example, a value in a JSON document,...
|
||
Use an asterix (*) to render an item as an unordered list item. | ||
Use an asterix (`*`) to render an item as an unordered list item. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
asterisk (throughout)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd like to see my suggestions made, but they are not essential.
No description provided.