search

OAI / learn.openapis.org

OpenAPI - Getting started, and the specification explained
https://learn.openapis.org/
Creative Commons Attribution 4.0 International
112 stars 56 forks source link

Add a project glossary #79

Closed handrews closed 6 months ago

handrews commented 7 months ago

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

miqui commented 6 months ago

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

ralfhandl commented 6 months ago

Should be mention what RFCs are?

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.

handrews commented 6 months ago

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

handrews commented 6 months ago

@earth2marsh @lornajane Move the historical note - I have no idea it wasn't at the end, totally an error on my part.