Documentation Initiative Update, UX Changes to

The documentation initiative was announced at DrupalCon Nashville nearly four months ago. In his keynote, Dries’ highlighted my blog post, in which I provided statistics and anecdotes about the challenges of’s documentation and evaluator experience. The documentation initiative aims to address these challenges. What’s happened since then?

I’ve worked over the past few months with a small team of contributors to propose solutions, build consensus, and make improvements to the documentation on Thank you to all of those that have been active in the issue queues and bi-weekly meetings!

The work has been focused on the initiative’s three goals:

  1. Make UX improvements to documentation on
  2. Improve existing Community Documentation by consolidating, re-organizing, and revising it.
  3. Introduce a new class of “Official” documentation that will be version controlled and subject to a review process that will enforce documentation standards.

I initially hoped to tackle these three goals in parallel, but quickly discovered that I needed to start with addressing UX issues on Why?

The UX challenges on make it very difficult to find and use documentation. They also make it hard to improve that documentation. I’ll explain.

I began planning by attempting to audit the existing documentation. As I traversed’s documentation in my browser I found it very challenging to get a comprehensive view of the information architecture. Manually compiling a list of pages by clicking on hundreds of documentation links isn’t much fun. It also made the engineer in me squirm.

So, I spun up a dev site (thanks for the help DA!) and ran some very hairy MySQL queries to get a sense of things. Even when looking at the Drupal 8 Community guide alone, the task was cumbersome and the results were messy. As an example of messy MySQL output, take a look at this unordered list of pages (belonging only to the Drupal 8 Community guide):

Understanding Drupal 8
- Overview
- Directory Structure
- Translation in Drupal 8
Understanding Drupal version numbers
- Which version of Drupal core should I install?
- Which version of contributed modules, themes, and translations should I install?
- When is the next release?
- Which version of Drupal am I running?
- Which version of a module or theme am I running?
- What about upgrading and backwards compatibility?
- Drupal release versions
- Development snapshots
- What do version numbers mean on contributed modules and themes?
- What are alpha and beta releases, and release candidates?
- Release stable version
- Drupal release history
Cron automated tasks
- Cron automated tasks overview
Installing Drupal 8
- Before a Drupal 8 installation
- Step 1: Get the Code
- Step 2: Install dependencies with composer
- Step 3: Create a database
- Step 4: Configure your installation
- Step 5: Run the installer
- Step 6: Status check
- Trusted Host settings
- Quick-start: launch a local demo version of Drupal 8 using 4 brief steps
Configuration management
- Changing the storage location of the sync directory
- Workflow using Drush
- File system based workflow
- Workflow using the Drupal UI
- Managing your site's configuration
- Keeping Your Local and Remote Sites Synchronized - Drupal 8
System requirements
- Browser requirements
- Web Server
- Limitations of 32-bit PHP
- Database requirements
- PHP requirements
- Database server
Extending Drupal 8
- Installing modules' Composer dependencies
- Installing Drupal 8 Modules
- Overview
- Installing Themes
- Interface guidelines (Seven admin theme)
- Finding Contributed Modules
- Uninstalling Modules
- Installing Modules from the Command Line
- Updating Modules
- Module Documentation and Help
- Troubleshooting
- Module Configuration
- Installing Sandbox Modules
Administering a Drupal 8 site
- Automated Cron
- Internal Page Cache
- Getting started with Drupal 8 administration
- Managing content
- Working with content types and fields
- Working with content types and fields
Migrating to Drupal
Multisite Drupal
- Multisite Drupal 8 considerations
- Multisite Drupal 8 Setup
- Multisite folder structure in Drupal 8
- Drupal 8 Multisite on a LAMP stack
Contributed modules
- Default Content
- Varbase Editor
- Business Rules
- Youtube Gallery
- Permissions by Term
- Block Style Plugins
- Developer Suite
- Commerce Braintree
- Feature Toggle - Deprecated
- Socialfeed
- HelloSign
- [marked for deletion]
- Marketing Cloud
- Drupal 8 Accessibility Features
- Contributed Modules for Extending Accessibility in Drupal 8
- Hide content properly
- External Accessibility Resources
Updating Drupal 8
- Update core via Composer
- Updating Drupal 8 - overview of options
- Update core manually
- Update core via Drush
- Update modules
Upgrading to Drupal 8
- Upgrade using Drush
- Preparing a site for upgrade to Drupal 8
- Upgrade using web browser
- Known issues when upgrading from Drupal 6 or 7 to Drupal 8
- Upgrading from Drupal 6 or 7 to Drupal 8
- Drupal 8 migrate modules
- Contributing to Migrate
- Learn key Drupal 8 concepts prior to upgrading
- Customize migrations when upgrading to Drupal 8
- Choosing the upgrade approach
Security in Drupal 8
- Writing secure code for Drupal 8
- Security of generated PHP files
- Secure configuration for site builders
- Secure Database Queries
- Drupal 8: Sanitizing Output
- US NIST Password Guidelines review
Mobile guide
- Responsive Images in Drupal 8
- Native mobile application development
- Mobile-specific website
- Web-based mobile apps
- Responsive web design
- Responsive Design + Server-side Components (RESS)
- Mobile testing tools
- Related mobile technologies
- Front-end performance
Multilingual guide
- Choosing and installing multilingual modules
- Translating configuration
- Translating content
- Install a language
- Enable language negotiation
- Menu translation in Drupal 8
'Clean URLs' in Drupal 8
- Fix Drupal 8 'Clean URLs' problems
Theming Drupal 8
- Defining a theme with an .info.yml file
- Drupal 8 Theme folder structure
- Adding Regions to a Theme
- Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 theme
- Classy themes css selectors
- Including Default Image Styles With Your Theme
- Working with breakpoints in Drupal 8
- Including Part Template
- Preprocessing and modifying attributes in a .theme file
- Using attributes in templates
- Sub-theming: Using Classy as a base theme
- Creating a Drupal 8 sub-theme, or sub-theme of sub-theme
- Creating advanced theme settings
- Theming differences between Drupal 6, 7 & 8
- Drupal Twig conversion instructions (tpl.php to html.twig)
- Upgrading classes on 7.x themes to 8.x
- Sub-Theme inheritance
- Creating automation tools for custom themes (Gulpjs)
- How to edit ALT tag on your site logo
- Theming Overview: How data is displayed
- Z-indexes in Drupal 8
- Using CSS pre-processors
- Add Google Webmasters Tools verification meta tag via the .theme file
Managing site performance and scalability
- Content Delivery Network [CDN]
- Blazy
- Server Scaling
Creating custom modules
- Building a Views display style plugin for Drupal 8
- Creating a custom Field
- Create a custom field widget
- Create a custom field formatter
- Create a custom field type
- A practical guide to building basic Drupal 8 modules
- Testing
- Defining a Block
- Settings
- Theming
- Basic structure
- Prepare a Module skeleton
- Add a composer.json file
- Naming and placing your Drupal 8 module
- Let Drupal 8 know about your module with an .info.yml file
- Adding Custom Blocks to your custom Module
- Add a Default Configuration
- Use Config in Block Display
- Process the Block Config Form
- Add a Form to the Block Configuration
- Create a custom block
- A "Hello World" Custom Page Module
- Going further
- Add a menu link
- Add a routing file
- Adding a basic controller
- Create a custom page
- Getting Started - Background & Prerequisites (Drupal 8)
- Defining and using your own configuration in Drupal 8
- Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module
- Understanding Hooks
- Add module to
- Event Systems Overview & How To Subscribe To and Dispatch Events
Drupal 8 APIs
- Runtime Assertions
- Installation & Setup Guide
- Configuration
- Converting D7 SimpleTests to Drupal 8
- Simpletest Class, File, and Namespace structure
- Types of tests in Drupal 8
- Javascript testing using Nightwatch
Converting Drupal 7 modules to Drupal 8
- Step 3: Convert hook\_menu() and forms
- Step 2: Convert automated tests to Drupal 8
- Debugging Drupal 8 module upgrades
- Step 1: Convert to
- Intro & Before you start: Setting up a Drupal 8 module dev environment
- Resources and tutorials
- D7 to D8 upgrade tutorial: Convert hook\_menu() and hook\_menu\_alter() to Drupal 8 APIs
- D7 to D8 Upgrade: Generated HTML
- D7 to D8 upgrade: fields, widgets and formatters
- WSCCI Conversion Guide
- WSCCI Conversion Guide - Best practices
- WSCCI Conversion Guide - Pass 3
- WSCCI Conversion Guide - Pass 2
- WSCCI Conversion Guide - Pass 1
- D7 to D8 tutorial: pathinfo module
- D7 to D8 upgrade tutorial: Pants module
- Step 5: How to upgrade D7 variables to D8's state system
- Step 4: Convert Drupal 7 Variables to Drupal 8 Configuration
Creating distributions
- How to Write a Drupal 8 Installation Profile
Core modules and themes
- Basic structure of Drupal 8
- deGov
- Thunder
- Install deGov 1.x
- Install deGov 2.x
- Upgrading from deGov 1.x to 2.x
Contributed themes
- Drupal8 W3CSS Theme Configuration
External Libraries in Core
- External PHP Libraries
- External JavaScript Libraries
- External CSS Libraries

Frankly, that list isn’t very helpful. It's 238 lines, it's unordered, and it shows only two levels of docs for a single guide. Representing more than that with MySQL is rough, and running a MySQL query (on a dev site) to generate it just isn’t a good or sustainable method of content auditing.

I determined that we need to do a better job of exposing the information architecture of’s documentation in the UI. So, that’s where I started to focus effort. By improving the visibility and discoverability of documentation we enable ourselves to better improve our documentation.

So, let’s talk about the documentation UI and UX.

Documentation Landing Page

I started with the documentation landing page and identified a few UX issues to resolve:

  1. The UI doesn’t tell me where I should start.
  2. The difference between the “Drupal 8 User Guide,” “Drupal 8 documentation,” and “Developer documentation” is not inherently obvious.
  3. The combination of Drupal 7, Drupal 8, and version-independent content is too much to easily scan and parse.

To resolve these issues, I dove into the customizations issue queue and the theme issue queue (bluecheese) and started submitting patches.

Take a gander at the before and after (still in dev) screenshots of this page:

In particular, the patches and content updates introduce the following salient changes:

  1. Add a “Getting Started” section at the top of the page to provide clear instruction to new users.
  2. Label and group the three different types of documentation, with descriptions for each:
  3. Official Documentation
  4. Community Guides
  5. API Reference
  6. Add “Official Guides” directly after “Getting Started” to steer users toward Official Guides.
  7. Add a listing of each top-level guide’s child pages.
  8. Add a menu to the sidebar (which can be used on child pages) to provide the user with a short list of the top-level documentation guides.
  9. Split the documentation landing page into two tabs for Drupal 7 and Drupal 8, defaulting to Drupal 8.
  10. Add a preprocessor to automatically generate invisible anchors for each section so that anchors can be used in the sidebar menu.

Status: Awaiting review from engineering team. These changes are not yet live on

The following issues must be reviewed and merged:

There will certainly be follow up issues to introduce more improvements, but these changes are a step in the right direction.

Next, let’s move down one level in the documentation hierarchy by visiting the Drupal 8 Community Guide.

Documentation Guide Nodes

Pages like Drupal 8 Community Guide and Drupal 8 User Guide are documentation_guide nodes. They’re also Organic Groups, which allows them to have their own menu, content, maintainers, etc. That’s cool.

Since a documentation_guide node can belong to another documentation_guide node, there’s also no limit to the depth to which guides can be nested. That makes for some very well hidden content. Not cool. But I digress.

I identified and addressed two UX issues on this page (they may look familiar):

  1. The “child guides” under the Drupal 8 Community Guide do not list their content on the parent guide node. For the Drupal 8 Community Guide, you’d need to open 32 separate guide pages just to learn what pages the child guides contain. That’s not to mention the grandchild guides and so forth.
  2. The sidebar has an incomplete list of top-level guides, and does not differentiate between various types of documentation.
  3. The guide maintainers are not listed.

Here’s are before and after screenshots of the Drupal 8 Community Guide:

These issues were resolved by re-using the menu and guide panes that I created for the documentation landing page, and filing a issue to add a maintainer panes (which was quickly addressed by @drumm).

I was astonished to see how many sub-guides are actually part of the parent Drupal 8 Community guide! This view is much more helpful than MySQL query output.

It exposes the fact that there are some very odd things going on in the information architecture. For instance, the Understanding Drupal 8 child guide has only a single page in it -- the overview page. It’s strange to have a guide that has an overview without subsequent content, and it feels very awkward as a reader. This is exactly the type of thing that is helpful to discover when refactoring the information architecture.

Status: Awaiting review from engineering team. These changes are not yet live on

The following issues must be reviewed and merged:

Next, let’s jump down two levels by clicking into the Front-end performance page in the Mobile Guide.

Documentation Page nodes

Each documentation guide node has one or more documentation pages that belong to it. Front-end performance is a documentation page that belongs to the Mobile Guide documentation guide, which belongs to the Drupal 8 Community Guide.

I identified two major UX issues on this page, all of which are particularly problematic on very long pages.

  1. There is no table of contents that lists the sections of the page.
  2. I cannot easily jump to (or even link to) sections of the page because most headings have no anchors in the markup.
  3. I cannot easily navigate to the next or previous pages in the guide.

To resolve these issues, I made the following changes:

  1. Added a new field formatter to the documentation page node “body” field that will automatically generate anchors for all h2, h3, and h4 tags (see hash tags to the left of each heading). This was accomplished by creating a new 7.x-2.x-dev branch of the Table of Contents module. Thank you to the maintainer @e0ipso for prompt responses and assistance!
  2. Added an automatically generated table of contents block to the right hand sidebar on documentation pages. Naturally this is also provided by the new Table of Contents module branch.
  3. Added a “tool tip” markup template to enable authors to call out important information.
  4. I’ve yet to tackle the task of creating a pager (previous and next links), but an issue has been created. Volunteers?

These UX changes make documentation pages more navigable. They also may encourage documentation contributors to better structure content by using headings.

Status: Awaiting review from engineering team. These changes are not yet live on

The following issues must be reviewed and merged:

That’s it for documentation pages. But wait, there’s more! Now we will take a few steps back and look how users find the documentation section.

Evaluator click path

We’ve looked at the UX for the documentation landing pages and many of the pages under it, but how do we get to /documentation in the first place? I’m particularly interested in ensuring those new Drupal users can easily download Drupal and intuitively find documentation that provides next steps.

At present, you must visit five separate pages and perform four clicks in order to simply download a Drupal tarball or zip file. I’d like to get that down to two clicks total.

To do that, we need to make changes to one or more of the following pages: 1) The home page, 2) The /try-drupal page, 3) the /download page.

I’ve proposed a few wireframes in this issue. Take a look at the current /download page as compared to one potential wireframe:

Notable changes include:

  • The zip file and tarball are available directly on the /download page, no need to visit the release node.
  • A separate link “release notes” link has been added.
  • The most relevant information (for new users) is displayed first -- Installation, Documentation, Requirements.
  • Secondary information (Translations, Modules, etc.) have been clearly placed in a separate section.

In addition to simplifying the click path in the web browser, some of the work required to accomplish this will also simplify the process of downloading Drupal on the command line.

As an example, let’s look at the new quick-start command that will ship with Drupal 8.6. This awesome new command makes it possible to install a Drupal demo application and login to in via your web browser in a single command. It does not require Composer, Drush, or Drupal Console, but it does require you to download Drupal first!

At present, you’d need to run this set of commands like this to quick-start:

curl -sS[x.y.z].zip --output drupal-[x.y.z].zip
unzip drupal-[x.y.z].zip
cd /path/to/drupal-[x.y.z]
php core/scripts/drupal quick-start demo_umami

Notice this code requires you to research and find the latest stable version of Drupal, then substitute it for the “[x.y.z]” snippets. You can’t copy and paste the code as-is and execute it.

By contrast, consider this:

curl -L > drupal.tar.gz
mkdir drupal && tar -zxvf drupal.tar.gz -C drupal --strip-components=1
cd drupal
php core/scripts/drupal quick-start demo_umami

This snippet makes use of a URL that always references the recommended version of Drupal, so you can directly copy, paste, and execute! No need to choose and specify the version of Drupal.

Status: Awaiting review from engineering team. These changes are not yet live on

The following issues must be reviewed and merged:


The documentation initiative making significant progress towards its first goal, to improve the user experience of discovering, navigating, and consuming documentation on This work will set us up to tackle the next goals of improving the existing documentation and drafting new documentation.

Multiple issues are in progress to improve the user experience for:

  • The documentation landing page
  • Documentation guides
  • Documentation pages
  • The /download page

We will continue to work on these issues and roll out improvements to documentation. We can then turn more attention to working on the docs themselves!

How you can help

Are you interested in helping with this work? You can.


Look for issues tagged with “Documentation Initiative” to follow progress and contribute!

In particular, we need help with the following issues:

Bi-weekly community “office hours”

Community members are invited to attend bi-weekly community “office hours.” This meeting is intended to provide a forum for status updates, discussion, feedback, etc. Feel free to propose agenda items in the #documentation channel on Drupal Slack. The meeting is held via Google Hangout on the first and third Tuesday of each month at 11am ET.

Slack channel

Contributors and interested community members are welcome to join #documentation channel on Drupal Slack.

Thank you!

I’d like to extend thanks to a few groups and individuals...

These are mostly great changes, thank you for tackling this really hard problem for the community!

Great stuff and really needed. Thanks for the work :)

Excellent summary, Matthew. It was really nice to see everything going on :-)

Add new comment

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.