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
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.
So, how does the new documentation system work exactly? It is based on two new content types:
- 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.
- 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.
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
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!
In recent weeks we've been making several small changes to Drupal.org: precursors to bigger things to come. First, we moved the user activity links to a user menu in the header. Next, we're moving the search function from the header to the top navigation. These changes aren't just to recover precious pixels so you can better enjoy those extra long issue summaries—these are the first step towards a new front page on Drupal.org.
As the Drupal 8 life-cycle has moved from development, to release, to adoption, we have adapted Drupal.org to support the needs of the project in the moment. And today, the need of the moment is to support the adoption journey.
As we make these changes you'll see echoes of the visual style we used when promoting the release of Drupal 8.
The Drupal wordmark region will help to define Drupal, and promote trying a demo.
A ribbon will promote contextual CTAs like learning more about Drupal 8.
The news feed will be tweaked.
DrupalCon will have a permanent home on the front page.
Community stats and featured case studies will be carried over(but may evolve).
The home page sponsorship format may change.
… a sneak preview of some new page elements and styles you'll see in the new home page.
Our first deployment will introduce the new layout and styles. Additional changes will follow as we introduce content to support our turn towards the adoption journey. Drupal evaluators beginning their adoption journey want to know who uses Drupal, and what business needs Drupal can solve. We will begin promoting specific success stories: solutions built in Drupal to meet a concrete need.What's next?
We're continuing to refine our content model and editorial workflow for the new front page. You'll see updates in the Drupal.org change notifications as we get closer to deployment.
Wondering why we're making these changes now? This turn towards the adoption journey is part of our changing priorities for the next 12 months.
Over the weekend, Drupal 8.2 beta was released. One of the reasons why I'm so excited about this release is that it ships with "more outside-in". In an "outside-in experience", you can click anything on the page, edit its configuration in place without having to navigate to the administration back end, and watch it take effect immediately. This kind of on-the-fly editorial experience could be a game changer for Drupal's usability.
When I last discussed turning Drupal outside-in, we were still in the conceptual stages, with mockups illustrating the concepts. Since then, those designs have gone through multiple rounds of feedback from Drupal's usability team and a round of user testing led by Cheppers. This study identified some issues and provided some insights which were incorporated into subsequent designs.
Two policy changes we introduced in Drupal 8—semantic versioning and experimental modules—have fundamentally changed Drupal's innovation model starting with Drupal 8. I should write a longer blog post about this, but the net result of those two changes is ongoing improvements with an easy upgrade path. In this case, it enabled us to add outside-in experiences to Drupal 8.2 instead of having to wait for Drupal 9. The authoring experience improvements we made in Drupal 8 are well-received, but that doesn't mean we are done. It's exciting that we can move much faster on making Drupal easier to use.In-place block configuration
As you can see from the image below, Drupal 8.2 adds the ability to trigger "Edit" mode, which currently highlights all blocks on the page. Clicking on one — in this case, the block with the site's name — pops out a new tray or sidebar. A content creator can change the site name directly from the tray, without having to navigate through Drupal's administrative interface to theme settings as they would have to in Drupal 7 and Drupal 8.1.Making adjustments to menus
In the second image, the pattern is applied to a menu block. You can make adjustments to the menu right from the new tray instead of having to navigate to the back end. Here the content creator changes the order of the menu links (moving "About us" after "Contact") and toggles the "Team" menu item from hidden to visible.In-context block placement
In Drupal 8.1 and prior, placing a new block on the page required navigating away from your front end into the administrative back end and noting the available regions. Once you discover where to go to add a block, which can in itself be a challenge, you'll have to learn about the different regions, and some trial and error might be required to place a block exactly where you want it to go.
Starting in Drupal 8.2, content creators can now just click "Place block" without navigating to a different page and knowing about available regions ahead of time. Clicking "Place block" will highlight the different possible locations for a block to be placed in.Next steps
These improvements are currently tagged "experimental". This means that anyone who downloads Drupal 8.2 can test these changes and provide feedback. It also means that we aren't quite satisfied with these changes yet and that you should expect to see this functionality improve between now and 8.2.0's release, and even after the Drupal 8.2.0 release.
As you probably noticed, things still look pretty raw in places; as an example, the forms in the tray are exposing too many visual details. There is more work to do to bring this functionality to the level of the designs. We're focused on improving that, as well as the underlying architecture and accessibility. Once we feel good about how it all works and looks, we'll remove the experimental label.
We deliberately postponed most of the design work to focus on introducing the fundamental concepts and patterns. That was an important first step. We wanted to enable Drupal developers to start experimenting with the outside-in pattern in Drupal 8.2. As part of that, we'll have to determine how this new pattern will apply broadly to Drupal core and the many contributed modules that would leverage it. Our hope is that once the outside-in work is stable and no longer experimental, it will trickle down to every Drupal module. At that point we can all work together, in parallel, on making Drupal much easier to use.
Users have proven time and again in usability studies to be extremely "preview-driven", so the ability to make quick configuration changes right from their front end, without becoming an expert in Drupal's information architecture, could be revolutionary for Drupal.
If you'd like to help get these features to stable release faster, please join us in the outside-in roadmap issue.Thank you
I'd also like to thank everyone who contributed to these features and reviewed them, including Bojhan, yoroy, pwolanin, andrewmacpherson, gtamas, petycomp, zsofimajor,SKAUGHT, nod_, effulgentsia, Wim Leers, catch, alexpott, and xjm.
Acquia's outside-in team celebrating that the outside-in patch was committed to Drupal 8.2 beta. Go team!