I would like to suggest some improvements to the Plugin documentation.
I'm a Drupal (6 and 7) trainer and will have to face students questions when I teach. I'm preparing D8 workshops.
First, I think it would be useful to distinguish between using plugins, and defining new plugins in order not to confuse those who are not already familiar with plugins.
Next, It seem's to me that "hooks" are already a mecanism to extend Drupal, and so, plugins competes with hooks in the mind of the student. It would be important to explain in what case we use hooks, and in what case we use plugins. Will some day all the hooks be converted to plugins ? what is the process to decide if a set of hooks become a plugin or not ? will hooks still exists but be reserved for "deeper API" (plugin would be more important for new comers than hooks).
It seem's that hooks will disapear for Drupal 9, I'm I right ? http://drupal.org/node/1509164 and http://drupal.org/node/1331486 don't talk about plugins but EventDispatcher.
"Module/hook system functions replaced with module_handler service" confuses me even more along with "hook based plugin discovery".