opensearch-api-specification icon indicating copy to clipboard operation
opensearch-api-specification copied to clipboard

Published 20 hours ago • verified publisher icon opensearch-project

[FEATURE] Require, standardize and import descriptions.

Open dblock opened this issue 7 months ago • 0 comments

Is your feature request related to a problem?

I think we will end up generating documentation from spec into https://github.com/opensearch-project/documentation-website. That site has a lot of inconsistencies around wording, defaults, or quoting. See https://github.com/opensearch-project/documentation-website/pull/7660 for an example.

What solution would you like?

  1. Import descriptions from https://github.com/opensearch-project/documentation-website.
  2. Require a description: field for all structures.
  3. Lint the descriptions. We already check spelling, but ensure that there are no decorative quotes (see https://github.com/opensearch-project/opensearch-api-specification/pull/402). No text that says "Default is blah", instead use a default: field. Consistently capitalize sentences and add periods at the end. Have the same tense.
  4. Lint the descriptions of tests.

dblock avatar Jul 10 '24 22:07 dblock