-
Notifications
You must be signed in to change notification settings - Fork 60
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
(DOCSP-11407): Update Parameters page #40
base: style-guide-v3
Are you sure you want to change the base?
(DOCSP-11407): Update Parameters page #40
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.
@melissamahoney-mongodb : Some additional thoughts here.
subject. For example, if the parameter is ``name``, the | ||
description might be "Server name, which becomes the initial host | ||
name of the server." | ||
description might be "Initial host name of the server." |
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.
question: Do we specify when to use the .. example::
block vs. inline? I think it should be more than one line, use a block.
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.
Out of scope here, but noted.
- Include any valid values and default value at the end of the | ||
description. Use the formats "Valid values are *n* and *n*." and | ||
"The default is *n*." For example, "Valid values are ``true`` and | ||
``false``." and "The default is ``false``." |
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.
suggestion: For body params, I have used:
- Include any valid values and default value at the end of the | |
description. Use the formats "Valid values are *n* and *n*." and | |
"The default is *n*." For example, "Valid values are ``true`` and | |
``false``." and "The default is ``false``." | |
- Include any valid values and default value at the end of the | |
description. Use the formats "Application accepts *m* and *n*." and | |
"The default is *n*." For example, "Atlas accepts ``true`` and | |
``false``." and "The default is ``false``." |
For responses, I use:
- Include any valid values and default value at the end of the | |
description. Use the formats "Valid values are *n* and *n*." and | |
"The default is *n*." For example, "Valid values are ``true`` and | |
``false``." and "The default is ``false``." | |
- Include any valid values and default value at the end of the | |
description. Use the formats "Application returns *m* or *n*." and | |
"The default is *n*." For example, "Atlas returns ``true`` or | |
``false``." and "The default is ``false``." |
The reason is to remove ambiguity as to whether something is probable, possible, or acceptable.
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.
This is a fair point, but also makes things harder for content reuse.
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.
suggestion: Yes, but that's a problem for later. Right now, we have an issue with trying to figure out "acceptable" vs. "possible". Making it active voice fixes that. If this is a living doc, make this change and we can revisit post-OpenAPI.
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.
This may be a moot point with OpenAPI, but it has been hard to determine the word with the best connotation: "acceptable"? "valid"? "possible"? All of those sound like they're part of what's acceptable.
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.
Also addressed this in PR #64
e8b9427
to
b14bb3d
Compare
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.
LGTM % 1 thought.
477cd3c
to
789181e
Compare
JIRA
Staging
Open Q: Do we want to standardize on how we do parameter tables in regards to column headings?