(DOCSP-11407): Update Parameters page

[melissamahoney-mongodb]

JIRA
Staging

Open Q: Do we want to standardize on how we do parameter tables in regards to column headings?

[atsansone]

@melissamahoney-mongodb : Some additional thoughts here.

[atsansone]

question: Do we specify when to use the .. example:: block vs. inline? I think it should be more than one line, use a block.

[melissamahoney-mongodb]

Out of scope here, but noted.

[atsansone]

suggestion: For body params, I have used:

Suggested change

	- 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:

Suggested change

	- 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.

[melissamahoney-mongodb]

This is a fair point, but also makes things harder for content reuse.

[atsansone]

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.

[atsansone]

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.

[melissamahoney-mongodb]

Also addressed this in PR #64

[atsansone]

LGTM % 1 thought.