Updated: Comment #1
The Drupal 8 API docs (and previous versions, of course) have implicitly coined a number of Drupal-specific terms. Examples:
- provider - used in plugin discovery and YAML parsing to refer to a module, distribution profile, etc. that might define plugins or provide YAML files
- entity - hard to even define what it means, really, if you don't already know!
- Dependency Injection Container or just "container"
These terms are used without explanation in API documentation. And I think they are being used consistently... However, they are Drupal-specific or have specific meanings in Drupal that are not generally known to software developers.
This makes it difficult for experienced programmers who are new to Drupal to understand what is going on by reading class/function API documentation.
a) Make a list of these terms, with definitions.
b) Put it in a Topic/@defgroup, probably in system.api.php
This way at least we could point programmers new to Drupal to this page so that they could learn about this terminology.
a) Make the list of possibly unfamiliar terms. This should exclude terms that are used on php.net or that are standard Computer Science terms, unless they have a Drupal-specific meaning that is different from their standard meaning.
b) Write definitions for these terms.
c) Create a @defgroup topic containing the terms and definitions. They should be listed alphabetically using our standard list formatting, like:
* - provider: A module, theme, or distribution profile, which may provide * YAML files, plugins, services, other classes, etc.
(Note: I'm not saying this is the definition we should use, necessarily, just that it's the format we should use.)
User interface changes
We'll have a central place on api.drupal.org to point new developers to when they get confused about terminology. No affect on the Drupal UI however.