Applying Lessons from the User Guide to Drupal Documentation

Before reading this, check out these other posts:

• Stranger in a familiar land: Comparing the novice's first impression of Drupal to other PHP frameworks by Matthew Grasmick, which points out the elephant in the room. Drupal's documentation in its current iteration can be a detractor to people evaluating the Drupal project.
• How can we fix Drupal's documentation by Adam Hoenich which outlines some ideas for how to evolve Drupal's documentation -- especially its governance.
• Three ways we can improve Drupal's evaluator experience by Dries Buytaert, the Drupal project's founder, in which he puts forth some recommendations as to how this situation can be improved.

After reading all of these I have lots of thoughts and feelings, and I don't yet know what I think the best path forward is. But I'm happy to see this conversation being highlighted and the continued discussion of how we can make Drupal's documentation even better. To that end, I think we can look to the User Guide project as an example we can learn from.

Learn from past successes

I want to point to the Drupal 8 User Guide project as an example of what can be accomplished through a documentation initiative. It wasn't ever an "official" initiative, but there was a lot of community involvement and excitement around it nonetheless, as well as more coordination and collective effort towards a goal than we typically see with regards to work on Drupal's documentation. While this particular guide only covers one aspect of Drupal, I believe it can serve as a good example for possible future documentation initiatives.

For reference, the readable version of the guide is here: https://www.drupal.org/docs/user_guide/en/index.html, and the project is located here: https://www.drupal.org/project/user_guide.

You can get some history of how this project was started, and how it evolved over time, by watching these two presentations:

• Let's Talk About Documentation, in which myself, Amber Matz, and Greg Dunlap researched how other OSS projects are doing documentation, and compared and contrasted that with Drupal in order to start a conversation about how it could be improved.
• Documentation is Getting An Overhaul, in which myself and Tatiana shared some of the ongoing changes to Drupal.org, and information about the progress of the User Guide project.
• And the initial proposal for the User Guide initiative.

We set out to solve a bunch of existing issues:

• No overall plan
• Limited scope
• Lack of peer review
• Lack of copy editing
• Tools that don't facilitate the governance model we wanted to impose
• The desire to have Drupal's documentation translated
• Guidelines, and conventions, for writers, and a process for enforcing them
• etc.

Things we learned that could be applied elsewhere:

Start with a plan

Once we knew we wanted to write the guide, and felt like we had some buy-in from the community, the first thing we did was make a plan. Jennifer and I met in person, and drafted an initial outline covering exactly what we felt the guide should contain. Then we shared that for feedback. Having this outline allowed us to know what was in scope, track the progress of the initiative, and get other people involved in a meaningful way (running a documentation sprint is a lot easier if you know what you want people to write).

In addition to the outline, we also defined a process that every page in the guide would go through.

1. Initial draft
2. Review: does it match our scope and guidelines?
3. Technical review: do the instructions work?
4. Copy editing
5. Finalize screenshots
6. Ready for publication

Image

Again, this allowed us to track progress, and helped with recruiting people because we had clearly-defined tasks for people to work on. We could also define that certain steps (copy editing, publication) could only be undertaken by specific people in order to allow for consistent quality control.

Use version control

While maybe not as friendly for someone who just wants to make a drive-by edit to a documentation page, using Git as the canonical source for the content of the guide has proven extremely valuable.

• Limit who can commit, ensuring that all content is vetted by the same procedure prior to being added
• Allow for better collaboration between multiple people working on the same content
• Facilitates a standarized review process
• Having a patch + review process helped attract contributors who might not otherwise participate. Many people are hesitant to edit a free-for-all page because they're concerned that they're not "doing it right." When they know there is a friendly review process in place, they are emboldened.
• Allows for opening issues and discussing changes before they're made (this is huge in comparison to the wiki-like nature of drupal.org)
• Allows for maintaining of translations. Once a page has been translated we have a way to track that the English version has changed, and thus the translated copies require an update.
• You can have a version of the documentation that matches a version of Drupal.

It does raise the barrier to entry for contribution. However, in my experience I generally feel the trade-offs are worth it.

Give people credit

A nice side effect of the use of version control in this case is that we can give people a commit credit for the work they've done. For better or worse, this is an important aspect of the contribution process. Writing documentation is often a thankless task, and we want to help elevate those that are contributing.

In addition to commit credits we also maintain an ATTRIBUTIONS.txt file for the guide, and individual attributions with each page.

Limit scope and define your audience

The user guide has a defined scope and audience.

From the guide:

> This guide was written mainly for people with minimal knowledge of the Drupal content management system. The topics will help them become skilled at installing, administering, site building, and/or maintaining the content of a Drupal-based website.

This allowed us to make critical decisions about what to include, what was too much, and where we maybe needed more information.

Additionally, writing documentation is one thing. Keeping it up-to-date is a whole other beast. Knowing the scope of what your documentation covers makes this easier.

Keeping the scope of what the guide covers allowed us to, well... finish the guide.

Oversight and governance are important

As Dries said in his post:

> It's hard to write world-class documentation by committee without good governance...

While the idea of a free-for-all wiki where anyone can come along and help with updates to the documentation certainly has its merits, it is also a promoter of sprawl and can lead to vastly inconsistent quality. In the end Jennifer and I didn't write all that much of the content. Instead, we helped others figure out where and how they could get involved, ensured that processes were followed by acting as gatekeepers, and worked hard to identify issues and adopt our plan in order to address them. I believe this allowed the guide to be completed.

Going forward we can help to identify areas that need improvement, facilitate translation teams who are doing the hard work of translating the content, and throughout all of this ensure consistent quality. But this only works because from the beginning it was made clear that this isn't a free-for-all, and there is a process.

The combination of a clear definition of scope and governance gives us the authority to say, "Thanks, but no thanks." With the existing wiki-like documentation there's no clear authority, which I believe leads to duplication, unnecessary content, and people feeling like they can't update or fix content written by someone else for fear of breaking some unwritten rules. Anyone wanting to improve things by deleting or re-writing is left to contend with the rebuttal from the author and no real recourse other than to decide they want to get into a battle or back off and leave it as-is. Clear scope and governance help solve these issues.

Automate!

Because we have a defined scope, and a set of strict formatting guidelines we are able to automate the process of creating screenshots for the guide. Almost every page in the guide contains multiple screenshots. Keeping those up-to-date with changes to Drupal core would be arduous -- which really means it wouldn't get done. Having an automated way to generate the majority of these ensures that when a new minor version of Drupal 8 is released we can just update all the screenshots. It also means we can generate screenshots for translated versions of the guide that show the Drupal UI with alternative languages installed.

Without being able to do this I'm not sure we would have decided to add screenshots to the whole guide. Its impossible to understate how much harder it is to maintain things like images and videos in comparison to text.

And, as a side-effect, this process serves as a sort of functional test suite for the guide. It often catches changes in Drupal core that require us to upgrade the step-by-step instructions in the guide.

Be prepared to explain again, and again, why we're taking this approach to writing documentation. After many years of wiki-style free-for-all on Drupal.org there are a lot of people who push back against imposing more oversight and control. Taking the time to explain the benefits of an approach like this and helping people to see how they can still contribute can be tedious, but it's worth it.

Videos

Additionally, Drupalize.Me is currently working on creating videos to complement the content of the user guide -- a task that we couldn't possibly take on without all of the above structures being in place. You can read more about the effort in Adding Free Videos to the Drupal 8 User Guide.

Recap

I hope that we can use some of the experience gained writing the Drupal 8 User Guide to help inform future decisions about how we create and maintain documentation for all of Drupal. Including:

• Defining a clear plan and scope for what should be included
• Implementing a process that facilitates peer review and oversight
• Evolving the governance of documentation in order to empower people with the authority to make decisions
• Create tooling that helps us to better maintain existing content

That, and of course, empower more people to get involved in creating high-quality documentation that matches people's expectations and makes Drupal look good.

I would love to hear your thoughts about adopting lessons learned from the user guide either in the comments here, or on one of the posts linked above.