Documentation overhaul

One of the biggest content areas on Drupal.org—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.

Background

Improving documentation on Drupal.org 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.

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 Drupal.org.
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.

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!