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

Comments

6

I've been involved with Drupal for about 18 months and I'm noticing that I would learn things the hard way, only to realize later that good documentation existed on Drupal.org, but it was buried too deep to find.

I'm sure that a lot of factors go into making content findable, but if our documentation on Drupal.org had clean URL's instead of node ids, every single page would jump in Search Engine rankings. That would mean more eyeballs on every page, more people finding the information they need, and more people making corrections when the information is out of date. It ought to be a easy win too, since Drupal can generate clean urls and set up redirects automatically.

I know, ideas are cheap, but it's at least worth a thought, right?

Yeah, absolutely. Findability is a problem. It's actually possible to add a custom path to a page on drupal.org, but since it has to be done manually it doesn't happen very often.

The downside to customizing the URL is that it adds a bit to the maintenance, since pages sometimes get superceded and repurposed.

In my opinion, Drupal's documentation has been by far it's weakest aspect in regards to making Drupal accessible to new developers. It lacks good examples, and answers/solutions more often than not come from other sources (deeply buried Drupal forum posts, StackOverflow threads, personal blogs, and comments below the actual documentation pages).

I really hate comparing Wordpress and Drupal, because in my mind, they're not even competitors. Their target markets are different and their toolsets vary greatly. However, if there's an area that Drupal could take a valuable lesson from, it would be in WP's codex. It is by far the most complete and useful CMS documentation that I have used, and Drupal would do well to mimic what WP has done in this specific case.

Lee, thank you for taking on this role! It's often a thankless task so I'm going to do that ahead of time.

:-)

-André

 

Lee, I'm wondering how you manage large amounts of content that has Drupal as the publishing platform. Do you author in a separate CMS and then bring the content into Drupal when you're ready to publish? Do you author directly in Drupal itself (using the editor within Drupal to author)? How do you handle the reviews by SMEs prior to publishing? 

I recently starting using Drupal as a help platform, after having used Mediawiki, Flare, Robohelp, and other tools in the past. I'm excited to leverage the Taxonomy, Views, and Acquia Search modules in Drupal to provide greater findability with the help content. 

The only difficult point right now is the authoring process. I'm just not sure what the best method is -- author in Drupal, author in DITA and bring into Drupal, author in some other way? 

Thanks for any insights you can share.

Tom

Having just been through the learning curve, I'd like to see at least part of the documentation be more systematically concrete. What I mean by that is the ability to directly map the concepts in the documentation to the objects found in the Drupal system.

The mental model that I've developed for myself, involves understanding Drupal as having 5 main properties:

- a resource manager (system files, user files, and the database, including entities)

- a configuration manager (the admin interface)

- a content manager (the content portion of the interface, plus layout, templates, and styling)

- a state change machine (the code) - specifically a dispatch-driven state change machine with a service oriented architecture

- a rapid application development tool

I think this approach allows for systematic coverage and decomposition into all or at least most of the areas of the Drupal system.

see http://internetcommons.ca/wiki/#notices for screencasts I created to sketch out this approach.

- Henrik