I recently performed an experiment in which I attempted to emulate the experience of a Drupal evaluator. I highlighted a few glaring pain points and shared my experience and conclusions in a blog post: Stranger in a familiar land: Comparing the novice's first impression of Drupal to other PHP frameworks.
That post sparked a tremendous degree of engagement. Many people commented, wrote responses on their own blogs, and voiced support on twitter. I was pleasantly surprised by the Drupal community's response, which was (nearly) uniform and highly corroborative. The jury is in. Drupal's evaluator experience is fraught.
A few notable long-form responses include:
- Three ways we can improve Drupal's evaluator experience (Dries @ dri.es)
- Applying Lessons from the Drupal 8 User Guide to Drupal Documentation (Joe Shindelar @ drupalize.me)
- How can we fix Drupal’s documentation? (@phenaproxima on medium.com)
In this post, I'd like to shift the conversation toward specific solutions. In particular, I'd like to focus on ways that we can improve the evaluator, developer, and site builder experiences through changes to our documentation.
Documentation Initiative Proposal
I think the Drupal community should undertake a first-class, long-term Documentation Initiative. ... it is absolutely worthy of becoming a full-fledged core initiative, with all the resources and support that existing initiatives enjoy.
I'd like to propose a formal Documentation Initiative for community consideration. In drafting this proposal, I've tried to incorporate:
- Lessons learned from the User Guide to Drupal Documentation
- Best practices already established by other PHP Frameworks (versioning, governance, prescriptive content, etc.)
- Drupal community requirements, as expressed in feedback to my initial blog post
There was a strong documentation effort undertaken not too long ago. It produced the Drupal 8 User Guide, which is far and away the best documentation on Drupal.org.
Unfortunately, Drupal.org's UX doesn't make the Drupal 8 User Guide easy to find or navigate. If you're lucky enough to find the Drupal 8 User Guide, you're unlikely to understand the difference between the Drupal 8 User Guide and competing documentation like the Drupal Community Guide. It makes for a very confusing experience.
I'd like to propose that we elevate the Drupal 8 User Guide to the status of "Official Documentation," and update the UX on Drupal.org to prominently feature the Official Documentation on major site entry points. A Drupal novice should encounter the Official Documentation essentially by default. By contrast, our Drupal Community documentation should be clearly identified as wiki-style and unofficial. We should minimize its visibility.
The team that produced the Drupal 8 User Guide established a set of admirable best practices. They implemented a governance process, version control, and documentation standards. They wrote their docs in markdown format and created a continuous integration process to generate and update screen shots of Drupal interfaces. Bravo.
We should adopt these best practices for all Official Documentation. In fact, we should go further. The Drupal 8 User Guide already has multiple branches corresponding with Drupal core minor and major versions. E.g., 8.5.x, 8.6.x, 9.0.x, etc. Let's integrate these into the Drupal.org UX, much in the way that Symfony and Laravel do. We should be able to intuitively identify and switch the documentation version.
Let's go further and lower the contribution barrier. At present, the Drupal 8 User Guide uses a Drupal Issue Queue. This means contributing by attaching patches and text files to issues. I, for one, would be immediately deterred from contributing by these requirements.
I'm going to be a bit controversial and propose that we use GitHub (or GitLab) to manage this instead. Allowing community members to use pull requests and an in-browser editor to contribute documentation will lower the bar while simultaneously leveraging version control and peer review. That would have massive impact. Drupal.org is apparently planning to migrate to one of these services. Let's not wait for that.
Lastly, I'd like to expand the Official Documentation by creating a new class of documentation that we're lacking: "The Official One Pager." The purpose of this class of documentation would be to provide a one page guide that prescribes the single recommended way to accomplish common Drupal tasks, like installing Drupal locally or using Configuration Management. Initially, I'd suggest starting with the following one page guides.
- Official Quick Start Guide (download, install, and log into Drupal)
- Official Configuration Management Guide (export, import, update, deploy)
- Official Composer Guide (install, update, extend, maintain, troubleshoot)
These are not intended to be exhaustively comprehensive. They are not intended to communicate all the myriad ways you can do things with Drupal. They will simply prescribe a straightforward path for accomplishing a discrete set of tasks. More detailed, nuanced, and comprehensive documentation will still be referenced and made visible.
Lastly, I'd like to propose that we prominently feature high quality, free training videos to help people get started. These should be provided as alternatives to the one page guides. Videos like this already exist. I believe that the Drupal Association could find willing partners to provide these materials in exchange for market visibility.
The picture of success
The documentation initiative would bring our documentation into line with competing frameworks. Let's take a quick look at Symfony as an example of a framework with stellar documentation.
Finding the official documentation is a breeze. Visiting Symfony.com displays a "Documentation" link as the second primary menu link. One intuitive click gets me to their official documentation.
The first "Getting Started" section begins with "Setup" as the first link. It's easy to find. Upon visiting the "Setup" page, I find that it has all of the elements of this proposal:
- It provides a single clear path forward that ends with a running web server and a working application (in one concise page).
- It is version controlled and it clearly indicates the framework version that the documentation refers to.
- It includes an "edit" button that allows you to contribute on GitHub.
- It links to free video tutorials.
- It links to more detailed guides for further reading.
The process of visiting Symfony.com, finding documentation, creating a brand new Symfony project, and visiting that new app in a browser took less than two minutes in practice. That is the bar. Drupal can do this too.
What you can do
Speak Up! To even begin this initiative, we need "buy-in" from the community and the Drupal Association. Assuming you, the reader, belong to one or both of these groups, speak up! Post a comment with your support, suggestions, or constructive criticism. This proposal needs review and modification by experienced community members.
Join a related BOF (Birds of a Feather) at DrupalCon Nashville and lend your voice or your help:
- Improving Drupal's Evaluator experience (docs!)
- An official Drupal local develop environment?
- Core Console: Adding a CLI tool to core
Get involved. If you'd like to contribute, or if you're in a position to facilitate the changes proposed in this post, contact me!
Let's make this a reality.