Three Million Words About Drupal

Actually, let’s make that 3.2 million words, covering 14,000 pages (up from 6,700 pages in 2010) and more than 8,500 topics. And that’s not counting the API docs.

However you measure it, the documentation on is massive and expanding quickly, so it’s with a great deal of excitement and some measure of trepidation that I’ve accepted the challenge of Documentation Team Lead, at least through the Drupal 8 release cycle. Certainly I’ve worked on some big documentation projects in my career, the largest being the Adobe Acrobat 8 SDK, where I was the lead technical editor, but that was a mere 10,000 pages (including the API docs) and I worked in anonymity surrounded by battle-hardened technical writers and managers. The Drupal docs, on the other hand, are an amazing labor of love created by a constantly shifting beehive of volunteers. And from what I know about bees, you can only lead them to the pollen by doing some kind of interpretive dance.

As part of this transition, Dries has asked me to write a few words about my vision for the Drupal documentation. After giving it a lot of thought, this is where I would like to see us moving:

To establish Drupal as the leading example of how to document a very large open source software project, not only in terms of the quality and currency of the content, but in the engagement of the community and the capability of the workflows and tools.

That’s a tall order and I have no illusions that we’ll completely realize that vision during my time as Docs Lead, but I definitely want to move the ball in that direction.

I also have two specific goals for the coming year:

  • Complete the Drupal 8 documentation
    With any software project, the first priority is simply to make sure the next release gets out the door. For the Drupal 8 documentation, we’ve taken the first step in that direction at a recent sprint in Montreal where we created an initial set of D8 documentation issues. With the Feature Complete date a little ways off, it’s still a little early to get much done, but there’ll be more sprints coming in the next few months. Hopefully I can make it to Drupalcon Portland, where things might gel further.
  • Implement better tools for documentation on
    Given the size of the documentation set, it is absolutely critical that we establish the ability to do some level of single-sourced content. In other words, that we’d finally be able to write and edit a chunk of content in one location, and then share it between multiple guides, between multiple versions of guides (D7, D8 etc.) and between the system Help and docs. We don’t necessarily need (and probably couldn’t manage) the very complex and sophisticated tools used in some large organizations (that kind of toolset usually requires well-trained permanent staff) but we do need some tools and processes for reusing content. The groundwork for single-sourcing has already been established under the guidance of the previous doc team leads and I’m hoping to work with the software team to take it through to implementation (although realistically this will likely follow the release of Drupal 8). I should note that we also desperately need the capability to do in-place editing (a la Spark).

I’ll also be reinstating regular office hours and online sprints (the first to coincide with the upcoming sprint weekend in March). Together we’ll work out the goals, guidelines and priorities for the docs team. As always, the idea is that by scoping out the work in some detail we can help people to find the tasks that suit their expertise and available time. Although contributions are welcome across the whole spectrum of the Drupal docs, my job as Team Lead will be to keep putting the focus on what we call the ‘curated’ content, which is everything related to the Drupal Core or that’s common to most Drupal installations. This is the content that really must be kept in good shape and it’s where you can make the biggest impact to the Drupal docs.

What I bring to the role and what I don’t

The main thing I bring to this role is a fair bit of technical communication experience, largely gained working on large enterprise applications and enterprise architectures, along with work editing developer and user-facing content. I’ve also spent nearly six years contributing, sometimes sporadically sometimes intensively, to the Drupal documentation effort.
But what I absolutely don’t bring to this role is any significant expertise as a developer, themer, accessibility expert, multilingual guru, security ninja, etc. For all that and more we need help from the entire community to write, review and edit the Drupal documentation. There’s a lot to be done and your contribution is desperately needed.

Finally, I wanted to note that if you’re interested in hiring me for your upcoming projects, you can learn more about my background through LinkedIn.