At Drupalize.Me, one of our goals is to provide learners with up-to-date resources that align with the latest best practices. To that end, I recently worked to update our tutorials to reflect the transition from PHP annotations to PHP attributes for plugin discovery. I blogged previously about why this transition is happening.
As Drupalize.Me’s tutorial library continues to grow, these kinds of changes touch ever larger numbers of existing tutorials. Plugins is an interesting one because we have tutorials that teach the inner workings of the Plugin API. And, we have tutorials about things like blocks, field types, and views plugins, that while not specifically about the Plugin API, make use of it. This ended up being one the most significant updates we’ve made since the release of Drupal 8.
Examples for Developers project.
Addressing annotations vs. attributes
One interesting challenge we faced was figuring out how to handle the fact that PHP annotations are still supported, even though attributes are now the recommended best practice. While we want to steer you toward the future, you’re still going to encounter annotations both in code and older documentation resources.
To help navigate this transition, I tried to add notes along the way that explain both approaches and provide guidance on when it might be appropriate to use one over the other. Hopefully this will help make informed decisions in your own work.
Keeping up with a moving target
Maintaining up-to-date documentation and tutorials for a constantly evolving platform like Drupal is a lot of work. And updates like this are possible because your membership ensures we can dedicate the time and resources required to make it happen. For this project alone, we spent around 30 hours writing, testing, reviewing, and editing.
And there’s still more to do. Our content on authoring custom Drush commands still needs to be updated. While not plugins, current versions of Drush also support the use of attributes instead of annotations. And, once Drupal core supports the use of attributes for custom entity type declarations, and migrate source plugins, we’ll need to update the relevant tutorials on our site.
At the end of the day, it’s all worth it when we know that learners are getting the best resources available. But it’s a reminder that documentation is a living thing—it’s never “done”, but constantly evolving alongside the software.
