Clarify complete vs self-contained documents

[handrews]

With apologies for the last-minute change, I encountered some confusion around the term "complete document", where it was mistaken for a single, self-contained OpenAPI Description. This is an attempt to solve that- we don't use "complete document" outside of this bit, so the awkward "syntactically complete" (with "self-contained" defined separately for clarity) probably does what we need. It is a bit awkward, though, so if anyone else can think of better words here please do speak up.

[mikekistler]

I have always found this section confusing.

I would like to suggest:

• We eliminate any appearance of "OpenAPI document" - I think all these should be "OpenAPI description". "OpenAPI description document" should likewise be simply "OpenAPI description".
• "document" should refer to a JSON or Yaml structure.

I left some suggestions to illustrate how this might look, but I think more work might still be needed.

[handrews]

@mikekistler there are some very important distinctions between "document" and "description" that need to be maintained here. All of this is really about precisely separating those concepts and highlighting the ambiguities that we've created by not having made that separation clear in the past.

[handrews]

@mikekistler @ralfhandl given how late we are in this cycle I'd really like to pull back and determine the minimum thing that is absolutely necessary to change.

I encountered a problem where someone from the workflows group read "complete document" and told other people that that meant it had no external references. That is an understandable error to me, so I added a word ("syntactically") and a term ("self-contained") to clarify.

How much of the rest of this is similarly needed to avoid egregiously wrong interpretations? If we had folks treating "complete document" as "no references", that would be a big problem as it's not what the text was intended to mean at all. I feel like the rest of this is just trying to optimize language, which I would prefer to do in 3.2.

I'd really like to just revert this to the minimal necessary change, get 3.0.4 and 3.1.1 out the door, and delve more deeply into how we present this in 3.2.

Probably just confusion on my part.

[handrews]

After an DM chat with @mikekistler I am backing out the one suggestion from him that I had accepted (as it did not change that wording in every occurrence) and he will consider a separate PR for more of a rewrite.

This PR is back to being just about fixing the "complete document" misunderstanding. If Mike's PR takes care of this in some better way I'm happy to drop this approach.