Drupal 8 is just around the corner, and it has reached an important milestone: beta-to-beta updates will be provided for each beta release going forward. That gives me some confidence that no major re-works are to be expected if I start building with Drupal 8. That said, we are still facing a sizable documentation gap regarding the changes in the API. My first encounter with this problem was when I was building a custom style plugin for Views.