One of the biggest content areas on—and one of the most important assets of any open source project—is documentation. Community-written Drupal documentation consists of about 10,000 pages. Preparations for the complete overhaul of the documentation tools were in the works for quite some time, and in the recent weeks we finally started to roll out the changes on the live site.


Improving documentation on has been a part of a larger effort to restructure content on the site based on content strategy we developed.

The new section comes after a few we launched earlier in the year. It also uses our new visual system, which will slowly expand into other areas.

Goals and process

The overall goal for the new Documentation section is to increase the quality of the community documentation.

On a more tactical level, we want to:

  • Introduce the concept of "maintainers" for distinct parts of documentation
  • Flatten deep documentation hierarchy
  • Split documentation per major Drupal version
  • Notify people about edits or new documentation
  • Make comments more useful

To achieve those goals, we went through the following process:

First, we wrote a bunch of user stories based on our user research and the story map exercise we went through with the Documentation Working Group members. Those stories cover all kinds of things different types of users do while using documentation tools.

We then wireframed our ideas for how the new documentation system should look and work. We ran a number of remote and in person usability testing sessions on those wireframes.

Our next step was to incorporate the feedback, update our wireframes, and create actual designs. And then we tested them again, in person, during DrupalCamp London.
Incorporated feedback again, and started building.

The new system

So, how does the new documentation system work exactly? It is based on two new content types:

  1. Documentation guide: a container content type. It will group documentation pages on a specific topic, and provide an ability to assign 'maintainers' for this group of pages (similar to maintainers for contributed projects). Additionally, users will be able to follow the guide and receive notifications about new pages added or existing pages edited.
  2. Documentation page: a content type for the actual documentation content. These live inside of documentation guides.

Documentation guide screenshot
Example of a new documentation guide

All of the documentation is split per major Drupal version, which means every documentation guide or page lives inside of one of a few top level 'buckets', e.g. Drupal 7 documentation, Drupal 8 documentation.
It is also possible to connect guides and pages to each other via a 'Related content' field, which should make it easier to discover relevant information. One of our next to-do’s is to provide an easy way to connect documentation guides to projects, enabling 'official' project documentation functionality.

More information on various design decisions we made for the new documentation system, and the reasons behind them, can be found in our DrupalCon New Orleans session (slides).

Current status

Right now, we have the new content types and related tools ready on
We are currently migrating existing documentation (all 10,000 pages!) into the new system. The first step is generic documentation (e.g. 'Structure Guide'), with contributed projects documentation to follow later.

While working on the migration, we are recruiting maintainers for the new guides. If you are interested in helping out, sign up in the issue. Please only sign up if you actually have some time to work on documentation in the near future.

There is a lot of work to be done post-migration (both by guide maintainers and regular readers/editors). The content is being migrated as-is, and it needs to be adapted for the new system. This means almost every single page needs to be edited. New fields (such as Summary) filled out with meaningful text (to replace text automatically generated by the migration script). A lot of pages include information for both Drupal 7 and Drupal 8, but this content needs to be split, with Drupal 8 information moved to pages in the appropriate version of the guide. These are just some of the steps that need to happen once the documentation has been migrated into the new system.

Next steps

As staff, we have a few follow-up tasks for minor improvements to the content types and tools. However, the bulk of the work is editing and improving the actual documentation, as I described above. This is in your hands now. Not only do we not have enough staff members to edit every single documentation page in a reasonable amount of time, we are also not subject matter experts for many of the topics, and so can't provide meaningful edits. The tools are ready, now it is up to the community to pick them up and write great documentation.

Documentation page screenshot
Example of a documentation page

Thank you

Lastly we want to say thanks.

Thanks to all the community volunteers who wrote those 10,000 pages over the years. Thanks to the Documentation Working Group members for their expertise, insight, and patience.

And, of course, thanks to staff. Unfortunately due to recent changes for the Engineering team, this will be the last section we'll have resources to work on for a while. This was a fun and important project to work on, and we are glad that we got to finish it. It is a beautiful legacy of the work we did together with some of our former colleagues: DyanneNova, japerry, and joshuami. Thank you!


droplet’s picture

Finally :)

Just 2 cents.

Highly recommend the design team take a look at:

Check it out how they handle the TIPs, GOTO PAGE, SNIPPETS, SWITCH DOC VERSION sections.

- Above "Example of a documentation page", the "DEVEL module tip" can put into a styled box. It's clearly separated from main docs.

- If I came from search engine, I can't locate to Version 8 from current page:

- Grid columns with different lines of title + desp, I feel that a bit annoyed and slow down my reading speed.

- Knowing that just a new start :), some section I think that still too detailed, a history book! e.g.:

I expected we can explain 3 sections in a SINGLE page. Other detailed explanation, we can put into LEARN MORE.

for example @see:

In most cases, I don't think Drupal is more complexity than other systems. Just we make it harder. We've given too much information to learners

- CORE first, SUGGESTION second.


No matter how cool is it for you. I think we should not put Drush & Drupal Console (non-CORE stuff) in the first section.

Single direction to Final gate:

Download Module From -> Extract It -> FTP it -> Enable it -> TIPS: Using Drush (link to Drush docs)

Option A: Download Module From
Option B: Drush it
Option C: Drupal Console
Option D: Composer

Option A: FTP
Option B: RYSNC
Option C: SSH

Option A: Drush enable
Option B: Core module page to enable



tvn’s picture

You have a lot of good points. And most of them are up to people who write/edit documentation. There isn't someone else who will come and fix it for us. Please go ahead and edit documentation pages when you see the content that is not ideal / cluttered.

beautifulmind’s picture

The design looks Simple & Clean. I do not get lost in lots of things on the page.
As long as efforts concerns, I am already doing my bit here:

Thank you.

dscoop’s picture

The design looks very nice! Smooth and simple for usability.

hermes_costell’s picture

User comments are one of the key things I look for on a Drupal documentation page. They're all the "gotchas", related links, etc which other users think are relevant, but not appropriate to put directly into the content. 

Now I have to click the little "Discuss" button for EVERY SINGLE DOCUMENTATION PAGE I GO TO. Sucks.