Standardize on "Description" as discussed on Slack

The learn site previously decided to use OpenAPI Description, but
hedged with terms like "OpenAPI Description document" and often
reverted to "OpenAPI document" in the text.

A recent discussion on Slack finally revealed a consensus that

* Re-defining "document" away from its intuitive meaning as a single
  coherent thing (file or network resource) is confusing
* "description" has more support than "definition" or "document"

Following up on that discussion, this change standardizes on:

* "OpenAPI Description" as the term for the logical entity
* "OAD" as a standardized abbreviation, alongside OAS and OAI
* "document" to mean either local file or network resource
* "documentation" only refers to generated or hand-written docs

Author: handrews

README.md

@@ -2,7 +2,7 @@
 
 <img alt="OpenAPI Initiative" src="assets/images/OpenAPI_Logo_Pantone-1.png" width="100%" height="auto">
 
-Are you new to the OpenAPI specification? 
+Are you new to the OpenAPI Specification?
 
 Read our [Getting started](https://learn.openapis.org/) page first.
 

best-practices.md

@@ -6,27 +6,27 @@ nav_order: 4
 
 # Best Practices
 
-This page contains general pieces of advice which do not strictly belong to the [Specification Explained](specification) chapter because they are not directly tied to the OpenAPI Specification.
+This page contains general pieces of advice which do not strictly belong to the [Specification Explained](specification) chapter because they are not directly tied to the OpenAPI Specification (OAS).
 
-However, they greatly simplify creating and maintaining OpenAPI documents, so they are worth keeping in mind.
+However, they greatly simplify creating and maintaining OpenAPI Descriptions (OADs), so they are worth keeping in mind.
 
 ## Use a Design-First Approach
 
-Traditionally, two main approaches exist when creating OpenAPI documents: **Code-first** and **Design-first**.
+Traditionally, two main approaches exist when creating OADs: **Code-first** and **Design-first**.
 
 - In the Code-first approach, **the API is first implemented in code**, and then its description is created from it, using code comments, code annotations or simply written from scratch. This approach does not require developers to learn another language so it is usually regarded as the easiest one.
 
 - Conversely, in Design-first, **the API description is written first** and then the code follows. The first obvious advantages are that the code already has a skeleton upon which to build, and that some tools can provide boilerplate code automatically.
 
-There have been a number of heated debates over the relative merits of these two approaches but, in the opinion of the OpenAPI Initiative, the importance of using **Design-first** cannot be stressed strongly enough.
+There have been a number of heated debates over the relative merits of these two approaches but, in the opinion of the OpenAPI Initiative (OAI), the importance of using **Design-first** cannot be stressed strongly enough.
 
 The reason is simple: **The number of APIs that can be created in code is far superior to what can be described in OpenAPI**. To emphasize: **OpenAPI is not capable of describing every possible HTTP API, it has limitations**.
 
 Therefore, unless these descriptive limitations are perfectly known and taken into account when coding the API, they will rear their ugly head later on when trying to create an OpenAPI description for it. At that point, the right fix will be to change the code so that it uses an API which can be actually described with OpenAPI (or switch to Design-first altogether).
 
 Sometimes, however, since it is late in the process, it will be preferred to twist the API description so that it matches *more or less* the actual API. It goes without saying that this leads to **unintuitive and incomplete descriptions**, that will rarely scale in the future.
 
-Finally, there exist a number of [validation tools](https://tools.openapis.org/categories/data-validators) that can verify that the implemented code adheres to the OpenAPI description. Running these tools as part of a Continuous Integration process allows changing the OpenAPI document with peace of mind, since deviations in the code behavior will be promptly detected.
+Finally, there exist a number of [validation tools](https://tools.openapis.org/categories/data-validators) that can verify that the implemented code adheres to the OpenAPI description. Running these tools as part of a Continuous Integration process allows changing the OpenAPI Description with peace of mind, since deviations in the code behavior will be promptly detected.
 
 > **Bottom line:**
 > OpenAPI opens the door to a [wealth of automated tools](https://tools.openapis.org). Make sure you use them!
@@ -41,45 +41,45 @@ For instance, it is also commonplace to use code annotations to generate an Open
 
 Alternatively, you can use a Continuous Integration test to ensure that the two sources stay consistent.
 
-## Add OpenAPI Documents to Source Control
+## Add OpenAPI Descriptions to Source Control
 
-OpenAPI descriptions are **not** just a documentation artifact: they are **first-class source files** which can drive a great number of automated processes, including boilerplate generation, unit testing and documentation rendering.
+OpenAPI Descriptions are **not** just a documentation artifact: they are **first-class source files** which can drive a great number of automated processes, including boilerplate generation, unit testing and documentation rendering.
 
-As such, OpenAPI description should be committed to source control, and, in fact, they should be among the first files to be committed. From there, they should also participate in Continuous Integration processes.
+As such, OADs should be committed to source control, and, in fact, they should be among the first files to be committed. From there, they should also participate in Continuous Integration processes.
 
-## Make the OpenAPI Documents Available to the Users
+## Make the OpenAPI Descriptions Available to the Users
 
-Beautifully-rendered documents can be very useful for the users of an API, but sometimes they might want to access the source OpenAPI description. For instance, to use tools to generate client code for them, or to build automated bindings for some language.
+Beautifully-rendered documentation can be very useful for the users of an API, but sometimes they might want to access the source OAD. For instance, to use tools to generate client code for them, or to build automated bindings for some language.
 
-Therefore, making the OpenAPI documents available to the users is an added bonus for them. The document can even be made available through the same API to allow runtime discovery.
+Therefore, making the OAD available to the users is an added bonus for them. The documents that make up the OAD can even be made available through the same API to allow runtime discovery.
 
-## There is Seldom Need to Write OpenAPI Documents by Hand
+## There is Seldom Need to Write OpenAPI Descriptions by Hand
 
-Since OpenAPI documents are plain text files, in an easy-to-read format (be it JSON or YAML), API designers are usually tempted to write them by hand.
+Since OADs are plain text documents, in an easy-to-read format (be it JSON or YAML), API designers are usually tempted to write them by hand.
 
 While there is nothing stopping you from doing this, and, in fact, hand-written API descriptions are usually the most terse and efficient, approaching any big project by such method is highly impractical.
 
 Instead, you should try the other existing creation methods and choose the one that better suits you and your team (No YAML or JSON knowledge needed!):
 
 - **OpenAPI Editors**: Be it [text editors](https://tools.openapis.org/categories/text-editors) or [GUI editors](https://tools.openapis.org/categories/gui-editors) they usually take care of repetitive tasks, allow you to keep a library of reusable components and provide real-time preview of the generated documentation.
 
-- **Domain-Specific Languages**: As its name indicates, [DSL](https://tools.openapis.org/categories/dsl)'s are API description languages tailored to specific development fields. A tool is then used to produce the OpenAPI document. A new language has to be learned, but, in return, extremely concise descriptions can be achieved.
+- **Domain-Specific Languages**: As its name indicates, [DSL](https://tools.openapis.org/categories/dsl)'s are API description languages tailored to specific development fields. A tool is then used to produce the OpenAPI Description. A new language has to be learned, but, in return, extremely concise descriptions can be achieved.
 
-- **Code Annotations**: Most programming languages allow you to _annotate_ the code, be it with specific syntax or with general code comments. These annotations, for example, can be used to extend a method signature with information regarding the API endpoint and HTTP method that lead to it. A tool can then parse the code annotations and generate OpenAPI documents automatically. This method fits very nicely with the code-first approach, so keep in mind the first advice given at the top of this page when using it (Use a Design-First Approach)...
+- **Code Annotations**: Most programming languages allow you to _annotate_ the code, be it with specific syntax or with general code comments. These annotations, for example, can be used to extend a method signature with information regarding the API endpoint and HTTP method that lead to it. A tool can then parse the code annotations and generate OADs automatically. This method fits very nicely with the code-first approach, so keep in mind the first advice given at the top of this page when using it (Use a Design-First Approach)...
 
-- **A Mix of All the Above**: It's perfectly possible to create the bulk of an OpenAPI document using an editor or DSL and then hand-tune the resulting file. Just be aware of the second advice above (Keep a Single Source of Truth): Once you modify a file **it becomes the source of truth** and the previous one should be discarded (maybe keep it as backup, but out of the sight and reach of children and newcomers to the project).
+- **A Mix of All the Above**: It's perfectly possible to create the bulk of an OpenAPI Description using an editor or DSL and then hand-tune the resulting file. Just be aware of the second advice above (Keep a Single Source of Truth): Once you modify a file **it becomes the source of truth** and the previous one should be discarded (maybe keep it as backup, but out of the sight and reach of children and newcomers to the project).
 
-## Working with Big Documents
+## Describing Large APIs
 
-This is a collection of small hints related to working with large API description documents.
+This is a collection of small hints related to working with large OADs.
 
 - **Do not repeat yourself** (The DRY principle). If the same piece of YAML or JSON appears more than once in the document, it's time to move it to the `components` section and reference it from other places using `$ref` (See [Reusing Descriptions](specification/components). Not only will the resulting document be smaller but it will also be much easier to maintain).
 
-  Components can be referenced from other files, so you can even reuse them across different API documents!
+  Components can be referenced from other documents, so you can even reuse them across different API descriptions!
 
-- **Split the document into several files**: Smaller files are easier to navigate, but too many of them are equally taxing. The key lies somewhere in the middle.
+- **Split the description into several documents**: Smaller files are easier to navigate, but too many of them are equally taxing. The key lies somewhere in the middle.
 
-  A good rule of thumb is to use the natural hierarchy present in URLs to build your file structure. For example, put all routes starting with `/users` (like `/users` and `/users/{id}`) in the same file (think of it as a "sub-API").
+  A good rule of thumb is to use the natural hierarchy present in URLs to build your directory structure. For example, put all routes starting with `/users` (like `/users` and `/users/{id}`) in the same file (think of it as a "sub-API").
 
   Bear in mind that some tools might have issues with large files, whereas some other tools might not handle too many files gracefully. The solution will have to take your toolkit into account.
 

index.md

@@ -7,15 +7,15 @@ nav_order: 1
 # Getting started
 ## Intended Audience
 
-This guide is directed at **HTTP-based API** designers and writers wishing to benefit from having their API formalized in an **OpenAPI Description document**.
+This guide is directed at **HTTP-based API** designers and writers wishing to benefit from having their API formalized in an **OpenAPI Description** (**OAD**).
 
 Machine-readable API descriptions are ubiquitous nowadays and **OpenAPI** is **the most broadly adopted industry standard for describing new APIs**. It is therefore worth learning it and getting it right from the start.
 
-These pages are a companion to the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0), helping the reader learn it and answering questions like "What is the best way to accomplish... ?" or "What is the purpose of... ?" that are naturally out of the scope of the specification.
+These pages are a companion to the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0) (OAS), helping the reader learn it and answering questions like "What is the best way to accomplish... ?" or "What is the purpose of... ?" that are naturally out of the scope of the specification.
 
 - If you are unsure if this guide is for you, read the next section below.
 - If you do not know what "API", "machine-readable description" or "OpenAPI" mean start by reading the [Introduction](introduction) chapter.
-- If this is your first time writing an **OpenAPI Description document** read [The OpenAPI Specification explained](specification) chapter for step-by-step tutorials.
+- If this is your first time writing an **OpenAPI Description** read [The OpenAPI Specification explained](specification) chapter for step-by-step tutorials.
 - If you already have **OpenAPI** experience but need help with a specific topic, take a look at the index of [The OpenAPI Specification explained](specification) chapter; it also includes advanced topics.
 - Finally, make sure you are aware of the recommended [Best Practices](best-practices) to take full advantage of **OpenAPI**!
 - And of course, you can always refer to the actual [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0) for reference.
@@ -36,6 +36,6 @@ On top of this, the **OpenAPI Specification** also provides you with:
 
 - **A non-proprietary format**: You have a say in the future direction of the Specification!
 - **The most developed tooling ecosystem**: As a direct result of the previous statement, OpenAPI offers a vast number of tools to work with it. Just take a quick look at [OpenAPI Tooling](https://tools.openapis.org).
-- **A format readable by both machines and humans**: Even though writing **OpenAPI** documents by hand is not the most convenient way of doing it (See [Best Practices](best-practices)), they are plain text files which can be easily browsed in case something needs to be debugged.
+- **A format readable by both machines and humans**: Even though writing OADs by hand is not the most convenient way of doing it (See [Best Practices](best-practices)), they are plain text files which can be easily browsed in case something needs to be debugged.
 
 So, choose your desired entry point from the list at the top of this page and start your journey!