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.
In short, the updates are necessary because Drupal is transitioning from annotations to native PHP attributes. And while annotations will continue to work for the foreseeable future, we wanted to make sure that the code examples, and recommendations, you find on our site are aligned with that code you’ll see in the latest versions of Drupal core.
What we did
This update was no small task and required:
- Writing a handful of new tutorials that cover PHP attributes from scratch.
- Refactoring existing tutorials related to the plugin API including: how plugins are discovered, how to define a new custom plugin type, and how to implement existing plugin types.
- Updating code examples in over 30 existing tutorials that previously used annotations, and converting them to use attributes instead.
- Minor updates to about 25 other tutorials that, while they didn’t feature code using annotations directly, still mentioned plugins in contexts that required revision.
- Testing everything to ensure our examples work, and learners aren’t left frustrated by out-of-date or incorrect examples.
- In the process, we also made updates to documentation on Drupal.org, and example code in the 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.
Add new comment