Add a project glossary #79
Conversation
This adds definitions and acronym expansions for terms that users of and potential contributors to OpenAPI projects are likely to encounter. It currently focuses on terms specific to OpenAPI, but could in the future also include some more standard terms to explain their usage in the OAS.
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
|
@handrews , @ralfhandl - hey folks, looks good overall, but one quick (minor) suggestion. Should be mention what RFCs are? And what they are intended to do? I only bring this up because the spec itself makes references to RFCs (yay!!). I know the sad fact is that most devs don't read RFCs, but hey we should strive to be more thorough. my 2 cents. |
The glossary explains acronyms invented by the OpenAPI Initiative. I'd refrain from explaining acronyms invented/owned by others. The RFC references in the spec link to the corresponding entries in appendix section A. References, which then link to the actual documents. I think this is "self-explaining" and doesn't have to be explained further. |
|
@miqui following up on what @ralfhandl said, there are plenty of places online to learn about RFCs. I might pull in some acronyms defined elsewhere, but only to explain how they are used in our specs (e.g. URI vs URL vs IRI, which people struggle with no matter how many RFCs or other documents you point them to- also there are multiple conflicting specs particularly for "URL"). But if we're not adapting or making a specific use (out of many possibilities) an abbreviation, I don't think we should take up extra space with it. |
Co-authored-by: Marsh Gardiner <marsh.gardiner@gmail.com>
when we get around to having a writing style guide, we should include that `e.g.,` should be set off by a trailing comma
definition might include a link to https://github.com/OAI/OpenAPI-Specification/blob/main/TOB.md ?
...where it should have been in the first place. Oops.
|
@earth2marsh @lornajane Move the historical note - I have no idea it wasn't at the end, totally an error on my part. |
This is an update of the "definitions" page from PR #69, which I will now close. I renamed it "glossary" becuase that's what more people were using when we talked about it last. The other material from the closed PR needs more rework before re-posting.
This adds definitions and acronym expansions for terms that users of and potential contributors to OpenAPI projects are likely to encounter. It currently focuses on terms specific to OpenAPI, but could in the future also include some more standard terms to explain their usage in the OAS.
The
nav_orderchanges ensure the glossary comes after the introduction but before everything else. Although perhaps it should go after "Getting Started" but before "Introduction"? Or maybe at the end? I do not have strong feelings about this as the sidebar menu isn't that long right now.