Last week, Matthew Grasmick stepped into the shoes of a developer who has no Drupal experience, and attempted to get a new "Hello world!" site up and running using four different PHP frameworks: WordPress, Laravel, Symfony and Drupal. He shared his experience in a transparent blog post. In addition to detailing the inefficiencies in Drupal's download process and end-user documentation, Matt also shows that out of the four frameworks, Drupal required the most steps to get installed.

While it is sobering to read, I'm glad Matthew brought this problem to the forefront. Having a good evaluator experience is critical as it has a direct impact on adoption rates. A lot goes into a successful evaluator experience: from learning what Drupal is, to understanding how it works, getting it installed and getting your first piece of content published.

So how can we make some very necessary improvements to Drupal's evaluator experience?

I like to think of the evaluator experience as a conversion funnel, similar to the purchase funnel developed in 1898 by E. St. Elmo Lewis. It maps an end-user journey from the moment a product attracts the user's attention to the point of use. It's useful to visualize the process as a funnel, because it helps us better understand where the roadblocks are and where to focus our efforts. For example, we know that more than 13 million people visited in 2017 (top of the funnel) and that approximately 75,000 new Drupal 8 websites launched in production (bottom of the funnel). A very large number of evaluators were lost as they moved down the conversion funnel. It would be good to better understand what goes on in between.

An example Drupal conversion funnel and the primary stakeholders for each level.

As you can see from the image above, the Drupal Association plays an important role at the top of the funnel; from educating people about Drupal, to providing a streamlined download experience on, to helping users find themes and modules, and much more.

The Drupal Association could do more to simplify the evaluator experience. For example, I like the idea of the Drupal Association offering and promoting a hosted, one-click trial service. This could be built by extending a service like into a hosted evaluation service, especially when combined with the upcoming Umami installation profile. (The existing "Try Drupal" program could evolve into a "Try hosting platforms" program. This could help resolve the expectation mismatch with the current "Try Drupal" program, which is currently more focused on showcasing hosting offerings than providing a seamless Drupal evaluation experience.)

The good news is that the Drupal Association recognizes the same needs, and in the past months, we have been working together on plans to improve Drupal's conversional funnel. The Drupal Association will share its 2018 execution plans in the upcoming weeks. As you'll see, the plans address some of the pain points for evaluators (though not necessarily through a hosted trial service, as that could take significant engineering and infrastructure resources).

The Documentation Working Group also plays a very important role in this process. After reading Matthew's post, I reached out to Joe Shindelar, who is a member of the Drupal Documentation Working Group. He explained that the Documentation Working Group has not been meeting regularly nor coordinating initiatives for some time.

It is time to rethink our approach around Drupal's documentation. Adam Hoenich, a long-time Drupal contributor, recommends that documentation becomes a full-fledged core initiative, including the addition of a Documentation Maintainer to the Core Committer team. His proposal includes blocking commits to Drupal on documentation.

I've no doubt that we have to evolve our governance model surrounding documentation. It's hard to write world-class documentation by committee without good governance and Adam's recommendations are compelling. Drupal's API documentation, for example, is governed by the Core Committers; while there is always room for improvement, it's really well-maintained. Some of you might remember that we had an official Documentation Maintainer role in the past, filled by Jennifer Hodgdon. Reinstating this position could bring documentation back into clearer focus and provide the necessary governance. I also suspect that a stronger emphasis on coordination, governance and recognition for documentation work, would inspire more contributors to help.

Last but not least, this also affects the Drupal (Core) Contributors. Evaluators often spend hours trying to get their web server configured, PHP installed or their database setup. As a community, we could help alleviate this pain by deciding to have a single, recommended default installation environment. For example, we could maintain and promote a Docker container (including an official docker-compose.yml) that ships with the latest version of Drupal. It would simplify many of our documentation efforts, and eliminate many roadblocks from the evaluation process.

To narrow down my recommendations, I would propose the following three steps:

  1. A single, recommended default installation environment (e.g. Docker container) for evaluators or developers taking their first steps in Drupal development.
  2. Infrastructure budget and engineering resources for the Drupal Association so they can offer a true hosted "Try Drupal" service.
  3. A Documentation Maintainer who can focus on end-user documentation, is a member of the Core Committer team and is responsible for defining the scope of what should be documented. Given the amount of work this position would entail, it would be ideal if this person could be at least partially funded.
Of course, there are many other solutions, but these are the areas I'd focus on. As always, success depends on our ability to align on solutions, coordinate all the work, and allocate the time and money to implement the necessary improvements. If you think you can help with any of the proposed steps, please let us know in the comments, and we'll help you get involved.


David Csonka (not verified):

I think one way in which the onboarding process for potential new adoptees could be improved significantly is if the "Try Drupal" space was restructured immediately to ask what the person's scope of expertise is.
- Are you an experienced PHP developer? Are you a new front-end dev? Are you a site builder? A stakeholder making adoption decisions?

Each of these types of people have different technical capabilities and experiential needs. They should be greeted by a more personalized experience that will help them succeed and have a more pleasant demonstration or setup.
Direct them to documentation or a guided tutorial as appropriate, so perhaps more jargon-heavy docs for the dev who wants the details, or a one-click spin up application like for the low-tech stakeholder or site builder.

Starting with "Pick a hosting provider" seems like putting the cart before the horse.

Ashraf Abed (not verified):

Hello Dries,
As someone who regularly trains non-Drupal users to become true Drupal 7 & 8 developers, this is a topic that is near & dear to me. This comment focuses on the documentation portion of the discussion. I've written a lots of high quality documentation (in the form of lesson plans). The feedback I've received on our documentation has been great, with many students saying they were most surprised with how high quality and thorough it all is. I think it's a main reason that our alumni don't tend to complain that Drupal is difficult to get started with. I would love to learn more about being a Documentation Maintainer.

Once the course is over and students leave the classroom setting, they're faced with the current state of's documentation. The state is understandable and represents hard work by many people. The frustrating thing, from my perspective, is that multiple talented technical writers have graduated my course and excitedly attempted to contribute to's documentation, but ultimately have submitted patches to modules' README files instead because it was easier to do that than to figure out how/where to contribute straight to

Here's one example of that happening. A graduate of my course & new Drupal user (cotterpinx, she's awesome!), submitted the following patch to panels:….

I don't expect you to read the patch, but it's a significant improvement to the documentation for newcomers. She wanted to make similar changes to documentation on and hit permissions / organization blocks. It's a shame, because her updates there would have been extremely valuable.

Lifting the barrier to contributing documentation has been on my mind so much lately that my company is actually hosting a free/public sprint (in the DC area) in about two weeks. We plan to do this either once a month or once every other month, depending on interest. The sprints are different than the usual sprint because they are almost fully geared towards new contributors and even Drupal evaluators (with at least HTML/CSS experience). We'll partner new Drupal users up with our alumni and let them knock out tasks together. Here's my (admittedly yet-to-be-refined) blog post about it:…

I hope I (and my Alumni) can be involved in reshaping's documentation. Thanks for the post!

Matthew Grasmick (not verified):

Additionally, I would be interested in becoming a documentation maintainer! Would love to learn more about the role and speak in more detail. I think that this highlights a significant opportunity for Drupal to advance its reputation and adoption.


Thanks Matthew. Your investment in the research and analysis shared in your blog post was impressive.

heddn (not verified):

We've seen the installation problem for a long time in DrupalCon sprinting efforts on Fridays. We do a full hour or two getting started workshop for hundreds of devs each conference to just get folks that really *want* to install Drupal and contribute onboarded. It has got to be easier, and things have gotten easier. Just not enough, nor fast enough.

I like the idea of a supported/official install of Drupal. Docker, VM, whatever, we need something.

Robert (not verified):

As a Symfony Framework developer I am still surprised & kinda shocked how Drupal is doing some things so much different comparing it to other PHP projects like Symfony/Laravel/Zend etc. The documentation is very confusing and scattered with lots of todo's and outdated content if you can find what your looking for at all.

Contributing to Drupal is a pain since you need to fully get into the eco system instead of just forking it and submitting a PR. If you manage to create an issue + patch file it just sits there for months without anyone taking action. Issues can be open for years and no one really cares or no one wants to be responsible for big decisions.

Also the code style is a very big negative for me personally. I have the feeling a lot of Drupal devs aren't open to make Drupal more attractive to other devs because they don't want to change their way of working (which is understandable, don't get me wrong). I think that a lack of clear leadership is the biggest pain point for the project right now. Looking at Symfony they have a structure of a lead, mergers and deciders. For Drupal it might be the same but I still haven't found who these people are and or how I can contact them.

Of course I know a lot of excellent work is done looking at the current state and there is a big history where there were no Githubs and Travis CIs around but it's time to move forward instead of staying in the past. Don't be afraid to make breaking changes once more in a major version (just like 7 -> 8 was done, great start!). To end with something positive: something I really enjoy is the community. I've not yet experienced such a warm and open group of people helping each other and having fun. :)

TL;DR I'm not surprised at all about the outcome of the referenced blog post.


Care to give a few examples of how you'd prefer to see things done instead? Or how the code style could be better?

Robert (not verified):

Weird... I replied to this but it didn't come through or something. In short what I think will help the project in the long run:

- Get clear leadership
- Switch to PSR coding style
- Use PR's instead of patch files
- Use more Symfony components (Config, Form, Security)
- Stop endless discussions that run for years

Currently Drupal is still so much on their own island and to make sure the project can keep up with other frameworks and CMS-es things need to change. The update from 7 to 8 was really amazing but things are taking way too long. Feel free to contact me by email to discuss it if you like.

Joe Shindelar (not verified):

+1! I think giving Drupal's documentation more oversight and governance will help to reduce sprawl, while also helping to ensure more consistent quality and coverage. All of which will lead to a better experience for newcomers.

Thanks for bringing this up Dries. And thanks Matthew for the original blog post which sparked the conversation. I have lots of thoughts ... here's a few :)

We introduced the concept of guides, and maintainers, on about 2 years ago now. This was done this way in response to long-standing requests for more oversight/review, while also trying to be receptive to concerns about what increasing the barrier to entry that something like version control would introduce. There has been low adoption. Though, some people have been stepping up to be maintainers for sure. I think that it might be worthwhile to take a little time to try and understand what is, and is not, working with this setup before deciding to make any kind of infrastructure changes. There was a lot of effort that went into it, and I think we can probably learn from all the conversations that have already been had as we go forward.

These changes also introduced some more public facing recognition for people contributing to documentation. Another thing that might be interesting to try and evaluate the effect of. They get their name on guides they maintain, and a list of guides on their profile. Much like being a contributed module maintainer. But, our community still doesn't place the same value on code contributions as it does documentation. That may never change, but I'm glad we're talking about it and continuing to find ways to improve the status quo. (Thanks everyone who writes documentation, you're my fav!)

The Documentation Working Group has fizzled over time. Initially a lot of effort was put into helping provide guidelines and tooling, followed by a long period of implementing. During which people moved on to other things. The goal of the group has always been to provide policies and guidelines, but the actual documentation is written and reviewed by the Drupal community. What we're talking about here is probably somewhere in-between. The DocsWG doesn't want to dictate what documentation should or should not contain, but does want to ensure that it's of high quality. It may be worthwhile to re-valuate the role, and members, of the group, in relation to evolving needs.

You absolutely have to define the scope of what it is that a documentation maintainer is going to maintain. Documentation encompasses a lot of things. And it's important to define what those are, and who is responsible for what. Community documentation pages on that document core APIs, modules, and how-to guides, the content parsed from core code and available on, the user guide, documentation about getting involved with the community, help pages within Drupal core, and more. I don't actually know off hand, but I would be willing to bet there are 1k+ pages of documentation on Some great, some not.

And while maybe not part of this discussion exactly, there's also all of the contributed module documentation. Which, especially for newcomers, is also part of Drupal's public face. This is especially true for popular modules and themes.

I think another initiative we can learn from is the Drupal 8 User Guide ( Which address many of the issues pointed out here, and in Adam's post which you linked to. Rather than continue to spew into this comment box though, I've written up a blog post that outlines some of those lessons here…

Ted Bowman (not verified):

Joe, thanks for your work on the documentation! I think the Drupal 8 user's guides was a big improvement.

What do you think about having the goal of "Quick Start" guide for Drupal that is limited to 5~10 minute read? Of course this would have to be a very opinionated guide that only presents 1 way of installing Drupal.

With other projects I have tried to learn I have really appreciated these.

This may actually require that we *first* have a local development environment that has an "official" status to make guide like this possible.

Jesus Manuel Olivas (not verified):

Totally agree providing a great user experience could be a big impact when making a decision while testing a CMS/framework or platform.

Since we started the DrupalConsole we focused on to provide a great user experience. That is why we decide to use the symfony/console and other third-party components and did our best to:
- Show really verbose and colorful error, warning, and other messages.
- Add support for multiple languages (we have support for about 20 languages now).
- Add interactive mode on commands to make it easy to the user asking questions related to the command is running.
- Add commands to generate boilerplate code.
- Add commands to debug the different Drupal subsystems (routing, config, state, container, plugins, etc.).

Related to starting a new Drupal 8 site. Drupal Console provides a command named `quick:start`.

Actually, this command is something we called a chain command
A chain command is a custom command that helps you automate multiple command execution, allowing you to define and read an external YAML file containing the definition name, options, and arguments of multiple commands and execute that list based on the sequence defined in the file.

DrupalConsole documentation about chain commands =>

YAML code is here:

The previous definition will execute several commands, in this case, commands that will download and install Drupal using SQLite, and finally start the PHP's built-in server.

Talking about providing an easy way to test Drupal 8.5 and the upcoming features as the umami profile. I wrote a blog post and a chain command, if interested in this topic this is the link…

Finally, I totally agree on providing a preconfigured docker stack will be a great idea.

Todd Smith (not verified):

I have five Drupal 7 sites. I'm more of a user than developer. All of my sites capabilities have been created via modules with occasional patches. I recently attended the Pacific NW Drupal Summit and there is negative sentiment with respect to Drupal 8 and its overall ease of use to get a site running. Drupal is incredibly powerful, yet incompleteness in the areas described above are a threat.

As an example I was on a call the other day and the question "Why not WordPress?" came up. In the web world of big shiny sites, business leaders have a hard time separating technology from requirements and requirements from implementation. Stories like the one that inspired this blog and comments need to be taken seriously. It's always hard to defend "but I hear Drupal is hard to learn". To a web end user they often translate this comment to mean that a Drupal site is hard to use. As we know poor usability can be accomplished with any tech.

I'm hopeful that recent blog provides inspiration. As a user of all the great capabilities. I am hopeful.


Thanks for your feedback, Todd. Hopefully my blog post illustrates that both myself and the Drupal Association take this serious.

Rick Manelius (not verified):

A word of caution on a "simple", official docker-compose.yml file. Full disclosure, I work on the DDEV local development project. Similar to Docksal, Lando, etc (there is a growing page containing the available solutions…), we are attempting to make Docker more approachable to the broader community.

However, there are challenges. The first is that the Windows community has 2-3 different approaches to installing Docker and the ideal (IMHO) approach of Docker for Windows requires a Windows 10 Pro license, which is not always possible for certain end-users on hardware that they can't modify due to company/org policies. This can leave them in the cold when everyone else has a more seamless experience. The other issue we've heard from trainers running classes at the beginner/intermediate level is that even a simple prerequisite (e.g. composer) can be a challenge because of inconsistent versions and installation methods across different versions of the OS. As a workaround, end-users can be directed to use composer within the container, but that doesn't feel like a proper UX.

I surface these issues because, from the end-user UX and developer DX perspective, this impacts their overall experience and it can be incredibly disheartening when they are finally excited to get around their local development pain points and then a hardware/software/docker version mismatch stops them dead in the water again. We've had to put a considerable amount of effort supporting Windows and see the value in that support, but its now always simple from an effort perspective to roll out and maintain as the Docker project evolves.


I wasn't aware of the challenges with installing or running Docker on Microsoft Windows. Thanks for sharing those facts, Rick!

Ashraf Abed (not verified):

This is why we've stuck with DrupalVM using virtualbox for now (even though drupalVM also has docker support). We don't ask what computers people have before accepting them to our courses, and we do whatever we have to to get users set up for local development when they arrive. DrupalVM w/virtualbox has worked more consistently across different OS's than docker so far. We'll re-evaluate in about 2 months in case docker improves in that aspect.

We do ask users to run composer within the VM to ensure consistent, well-documented / predictable behavior. Overall, it is not easy to set up (or to run composer commands in the VM on mediocre computers - that's rough), but with good documentation it's been fine.

We actually have a 'tricky' workaround we use in class to allow users to truly use composer without most of the permission / timeout / etc issues, even if their computers cannot handle composer. I'll write a blog post about the approach and comment back.

Vil (not verified):

Thanks for sharing @Rick. I would prefer a Virtualbox + Vagrant based solution, as opposed to Docker. I use Ubuntu, but I believe Virtualbox + Vagrant works pretty much the same way in Apple, Windows and Linux, right?

Perhaps an Ubuntu 16.04 Vagrant box pre-installed with latest Composer, MySQL, PHP, etc. would be an easy way to get started? is fairly close to this set up, and could be used for inspiration. Perhaps Nick can be contacted and asked for collaboration to make a Drupal-oriented Vagrant box?

Vil (not verified):

I have tried DrupalVM, but think it is a bit too over-engineered and complicated ... I feel that Scotch Box strikes a good balance between usefulness and simplicity, and not getting in the way of my productivity with features I don't need.

thamas (not verified):

We run a Drupal introduction training some month ago and chose Acquia DevDesktop to let attendees have a Drupal installation on their laptops. We did that because we had a very diverse group (most of them without any web development experience) and we looked for the simplest solution for a good first impression. And it worked well for most of them but not for everyone. Typically they had laptops with Windows and sometimes they had no rights for same modifications needed by Drupal install or had not enough memory on older machines.

Ted Bowman (not verified):

For those interested a have set up a series of BoF's at DrupalCon Nashville related to this topic:

Improving Drupal's Evalutator experience:

An official Drupal local develop environment?:…

Core Console: Adding a CLI tool to core:…

I am no way an expert in these areas but it seems like these are urgent needs so I grabbed the BoF space in hope that there is more interest.

Add new comment

The content of this field is kept private and will not be shown publicly.

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.