Improve docs about summary and description

[InfoSec812]

Addresses #2392 by creating 2 new definitions at the beginning of the specification and linking to those definitions wherever summary and description are used in the standard.

@MikeRalphson I think that this can safely "balance" between verbosity and clarity. Looking forward to your thoughts.

[LikeLakers2]

You ought to include those headers in the Table of Contents, for consistency with how everything else is in the TOC. :)

[MikeRalphson]

Please don't reintroduce the 120-character suggested limit, this was deliberately dropped in v3.0.0. I'm not convinced by the value of top level definitions as a solution to your issue, as it requires readers to have two regions of the spec. in mind at the same time.

[InfoSec812]

I'm not convinced by the value of top level definitions as a solution to your issue, as it requires readers to have two regions of the spec. in mind at the same time.

I'm interested in better understanding your concerns @MikeRalphson ... In my mind, the links are there for if someone wants clarification, but they can be ignored when users of the Spec are already familiar with the differences between summary/description.

[hkosova]

It MUST be plaintext and not contain formatting like Markdown or HTML.

This sentence is probaby unnecessary because the "Rich Text Formatting" section states that only description fields support Markdown.

Plus, "must not contain formatting" may be interpreted as if validators/linters need to explicitly check for the presence of Markdown / HTML tags in summaries and in that case flag the definition as invalid, which looks like an overkill.

[MikeRalphson]

I'm interested in better understanding your concerns @MikeRalphson ... In my mind, the links are there for if someone wants clarification, but they can be ignored when users of the Spec are already familiar with the differences between summary/description.

I think the fact that they can be ignored points towards the fact that in their current state, they're merely redundant, not adding anything above and beyond the summary and description field descriptions in the field tables. But, and this is a biggie, I'm just one voice, and the point of the PR is to let others weigh in.

[InfoSec812]

@MikeRalphson With regards to the definitions and reciprocal links, I feel like it is useful for those who are NOT as deeply familiar with the OAS standards so that they can quickly become familiar without having to seek out an expert to get an explanation. My own case being a potential example. Even though I am a frequent and regular user of OAS, I was not aware and did not quickly see the reasoning of why summary/description were different and how they were different. I would like to think that we could create a standards document which is more inclusive and fosters people at all levels of experience to be able to understand and contribute to the discussion.

[InfoSec812]

This sentence is probably unnecessary because the "Rich Text Formatting" section states that only description fields support Markdown.

Resolved, and agreed that it is well explained further down...

Plus, "must not contain formatting" may be interpreted as if validators/linters need to explicitly check for the presence of Markdown / HTML tags in summaries and in that case flag the definition as invalid, which looks like an overkill.

Removed.