Drupal 8 adoption is flagging. Why? I tried to lay my biases and assumptions aside and set out to find the answer. What I found surprised me.

I decided to perform an experiment. Placing myself (as much as possible) in the shoes of a senior developer without any Drupal experience, I attempted to get a new "Hello World" site up and running in four different PHP frameworks: Wordpress, Laravel, Symfony, and Drupal.

I set a few ground rules for myself:

Start at square 1. Google "Drupal" (or Wordpress, etc.).

Use only information found organically via my Google search and subsequent clicks.

Take the path of least resistance. In other words, choose the easy way when more than one option exists.

Avoid the command line when possible.

Measurements:

Time required.

Number of clicks in web browser.

Number of CLI commands run.

I do not claim that this experiment was purely objective or scientific. The fact is that I do have plenty of Drupal, PHP, and CLI experience and I'm not a good representation of the average Drupal novice. However, I think that the exercise did provide a rough sense of the developer experience.

My system setup before beginning:

Operating system: Mac OSX 10.13.3

Installed libraries: PHP Git Composer Vagrant Virtualbox MAMP (MySql, Apache, PHP)

Presumed knowledge/skills: Ability to create new VirtualHost entry in Apache (via MAMP) Ability to create new MySQL database (via MAMP) Ability to use CLI to execute basic commands ( cd , cp , mkdir , git ) and to copy and paste commands from docs.



TLDR; these are the results:

Broken into 3 categories:

Creating a site via path of least resistance Creating a site explicitly on my local machine Creating a site explicitly on a free, organically discoverable hosting provider

Creating a site via path of least resistance

Framework Clicks Commands run Local Total Time Wordpress 7 0 no 1:14 Symfony 3 3 yes 1:55 Drupal (pantheon) 11 0 no 5:04 Laravel 3 9 yes 17:28

Creating a site on local machine

Framework Clicks Commands run Total Time Symfony 3 3 1:55 Wordpress 7 0 7:51 Laravel 3 9 17:28 Drupal *20+ 0 *15:00+

* Spoiler, I gave up counting clicks and reading docs on Drupal.org after 20 clicks and 15 minutes.

Creating a hosted site

Framework Host Clicks Local Total Time Wordpress wordpress.com 7 no 1:14 Symfony (heroku) heroku.com 10 no 4:21 Drupal (pantheon) pantheon.io 11 no 5:04 Drupal (acquia) acquia.com 8 no 16:34

Wordpress is a clear winner for the fastest and simplest setup via the path of least resistance, which is (no suprise) on a hosted service. Symfony was the clear front runner for setup on my local machine.

Analysis

Hosted Site

In each case, setting up a new site with a free hosting provider (when available) proved to be the simplest solution. But, the experience of doing it with Drupal was the least intuitive.

Drupal is the only framework that made me choose a hosting provider and navigate through a hosting UI to find the framework's homepage. I was presented with the choice between Patheon, Acquia, and 1&1. As an (imagined) Drupal noob, I had no idea which to pick and I was tempted to veer off course to research the providers.

Instead I chose Pantheon purely because it was the first option listed. I later learned that the ordering of hosting providers is randomized. With Pantheon, I was walked through an 11 click and 5 minute process that eventually dropped me onto the homepage of my new Drupal site. I decided to try the Acquia path just for fun. 8 clicks and ~16 minutes later, I was back on a Drupal homepage. This process was not without some consternation.

With both Pantheon and Acquia, I found myself in the unexpected territory of a hosting provider's UI. In the case of Acquia's UI, it took me a full minute of staring at the screen before I could determine which link would actually "get me into Drupal." This blog post describes the experience well (with screenshots).

If I hadn't already been somewhat familiar with both Pantheon and Acquia, I would have found it bewildering to navigate through a landscape of environments, servers, and workflows before even seeing Drupal. It left plenty of room for improvement.

Let's move on to the experience of setting up a new site locally.

Local site

In terms of the technical setup, both Symfony and Laravel had superior developer experiences, primarily because both provided out-of-the-box development environments.

Symfony had a surprisingly easy set of instructions that did everything from create the project to launch the web server in less than 2 minutes. Wow. I wish Drupal would replicate that. We have a lot to learn from the Symfony community. I didn't need to think about LAMP stacks or VMs at all.

Laravel on the other hand, provided a ready-to-go Vagrant box for my needs. While somewhat weighty and complex, it was wonderful to have a clear go-to solution that just worked, albeit slowly. I'm not a huge fan of Vagrant, but I am a huge fan of plug n' play.

Wordpress and Drupal had similar setup experiences from a technical perspective. Both required a tarball download and the configuration of a LAMP stack. For many developers, particularly those new to PHP or those on Windows, LAMP stack setup isn't trivial. It can be a serious impediment to require that users first research, choose, and set up a LAMP stack. It reminds me of Carl Sagan's quote "If you wish to make an apple pie from scratch, you must first invent the universe." It feels like you need to invent the universe before building a Drupal site.

Choosing and providing a standard solution for this, as Laravel and Symfony have, would be a great improvement. Drupal claims to be developer focused, but Symfony and Laravel do a much better job of enabling developers out-of-the-box.

But let's move on to the biggest and most interesting difference.

The biggest difference

The experience of navigating Drupal documentation as an (imagined) novice was confusing, frustrating, and ultimately demoralizing. After 20 minutes of clicking back and forth between various conflicting and competing documentation guides, I was seriously questioning whether I even wanted to finish this blog post.

I'm going to give a play-by-play of my user experience, and wrap up with a summary with the underlying issues that it reveals.

I began by Googling "Drupal" and clicking on the first organic result, drupal.org. I spotted the "get the code" link pretty quickly and followed that with a click on "Download Drupal 8.4.4". A little redundant, but I wasn't feeling annoyed yet.

I was taken to the release page for Drupal 8.4.4, which was filled with release notes, known issues, and a slew of information that was irrelevant to my purposes and somewhat overwhelming. Ignoring 90% of the page content, I clicked "Download tar.gz" and then hunted down the sidebar content to find "Learn how to install Drupal". I've already clicked some form of "Download / get code" three times at this point, but I'm feeling like I'm almost done. If only.

I land on the Installing Drupal 8 section of the Drupal 8 docs guide, the first line of which reads:

I ask myself...

"Am I not in the Drupal 8 User Guide? "

"Is that a different guide?"

"Should I read that instead?"

I decide that I should follow the link. This takes me to Chapter 3. Installation of the Drupal 8 User Guide which is a completely different set of docs. I think to myself, "this is weird, but I'm going to go with it." I also notice that I'm on Chapter 3, which means that I may have skipped over important information.

I decide to start at the beginning and visit Chapter 1. Understanding Drupal. This is filled with information on Drupal terminology, licensing, data types, and architecture. In fact, there are 19 sections that preceed the Installation chapter. I am decidedly not interested in learning this yet, I'm just trying to get a basic site running! My experiences with Wordpress, Symfony, and Laravel did not subject me anything like this as a first step. I'm going to abandon the background info and go back to Chapter 3.

I encounter "3.1. Concept: Server Requirements", which gives me an overview of various types of web servers, including Hiawatha and Microsoft IIS. I'll skip over that and get down to business. Next is "3.2. Concept: Additional Tools," which tells me all about Drush, Git, Composer, Devel, Drupal Console, Coder, and other tools. I still haven't found any instructions and I'm starting to doubt that I made the right choice in following the Drupal 8 User Guide to get a quick start. I decide to go back to Installing Drupal 8 section of the Drupal 8 docs guide, where I initially started.

I'll start with the first section, "Before a Drupal 8 installation". This contains a preamble with the words:

Documentation for Drupal 8 on drupal.org is found in two separate areas... The basic differences between the two documentation areas are discussed here.

I decide that I'll click the link because I do want to know what the hell is going on with the documentation. I'm rewarded with the following choice snippets of text:

if you are trying to find a clear step-by-step guide here at drupal.org (d.o) to achieve exactly what you want to do, (first of all, "Good luck,")

and:

Which guide you should start with? I can not answer that, since by all appearances to me, the documentation at d.o has all the appearances of being a war waged on two fronts.

and a literal cry for help:

If you, like me, cherish daunting challenges, and welcome the prospect of helping with what I loosely, and comedic-ly, refer to as the 'train wreck' that the d.o documentation is...

And if you find pleasure knowing you have made contributions which help thousands of people, without a need for gratification from others...

Help.

Are. You. Kidding. At this point the farce is wearing thin. Drupal is a great framework and I've been proud to be a contributor and member of the community for many years. As I go through this exercise, I'm becoming embarrassed on behalf of Drupal.

I decide to just push forward. Read the docs, install Drupal, and go take a walk. I continue reading "Before a Drupal 8 installation". I don't get halfway through the section before I am told to see another guide on Local server setup. That guide has 10 chapters of its own each with multiple sections. There is no way I need to wade through all of that to get a Drupal site set up. Forget it, I'll just use MAMP since there is no clear recommendation or clear path forward.

Before I even leave the "Before a Drupal 8 installation" section, I encounter this text:

h1. Three Drupal sites per live site By the way, when you have a live Drupal site, you will at times have a total of three Drupal sites running on your computer or web host.

Ignoring the fact that I'm reading a section that starts with "By the way," this is just wrong. No one runs 3 versions of the same Drupal site on their local machine, and those who have multiple environments in the cloud may or may not have three of them. Why is this section even on a "Before a Drupal 8 installation" page?

Why would a "Before a Drupal 8 installation" page contain this:

Before you do make changes to your live site, you will want to grab a copy of your Drupal codebase, and your Drupal database, and use them to create a backup site to make sure you have what you need to recreate your live site as it is in the event that your changes to your live site go horribly wrong, for whatever reason. You can, of course, delete the 'backup' installation after you establish that your backup codebase and database are 'good', but be sure to keep at least three separate sets of that codebase/database set, in three separate locations. Three separate locations mean separate online companies or separate USB drives/hard drives in separate locations. This will prepare for a disaster: for example, a fire at your home/place of business, or one of your online storage facilities getting hacked into.

I just wanted to install Drupal. I'm 20 clicks into a rat's nest of documentation, I've stumbled across three different guides, one apparent documentation war, a suggestion that changes to my live site may go "horribly wrong," and instructions to place my non-existent Drupal site's backups onto three separate USB drives stored in geographically disparate locations in case of fire or hacking.

I stopped counting clicks at this point and restarted the exercise using the knowledge that I already have. Even then, it took longer than getting WordPress set up locally (for the first time ever).

Honestly, if I were evaluating Drupal, this experience alone would make me choose a different framework.

Conclusions

As compared to other popular PHP frameworks, the experience of setting up a new "hello world" Drupal site as a novice is uniquely difficult and frustrating.

The first major roadblock encountered is documentation, which is sprawling, conflicting, redundant, and disorganized. To compete with other frameworks, we need to have clear, concise, and consolidated documentation that explicitly indicates the recommended/supported/official way to do things. I understand that Drupal is flexible and allows us to do things in infinite ways. It's not unique in that way. We can still provide clear instruction.

The technical process of setting up a Drupal site isn't the worst, but also not the best in any category. It lacks the "out-of-the-box" tools that Symfony and Laravel provide for getting quickly spun up on a web server, and it lacks the simplicity and speed of Wordpress.

I think that Drupal can be a framework for ambitious sites and also one that is a joy to use, even for novices.

We need to ...

Improve our documentation. Docs should be clear, concise, and consolidated Docs should explicitly indicate the recommended/supported/official way to do things Docs should be both curated and very easy to contribute to

Provide an official, documented, out-of-the-box solution for spinning up new Drupal sites quickly and easily on a local machine.

I am frankly hesitant to jump into the fray and help solve these problems. The scope of the technical and documentation problems isn't intimidating. The fact that there are many stakeholders and a pre-existing controversy is intimidating.

To be successful, we need coordination from the Drupal Association to make changes on Drupal.org. We need buy-in from the community to support an "official" solution for local development. We need collaboration from the Drupal User Guide maintainers and the Drupal 8 Guide maintainers.

Given those challenges, I'm hesitant. But I'm still willing to give it a shot.

If you're in a position to help address these challenges, contact me. Let's fix this.