Drupal CMS Guide Update: The Challenge of Documenting a Fast-Moving Open Source Product

Monday, Jan. 13th – 2 days before the Drupal CMS product launch

I sat down at my desk this morning with the intent of working on creating screenshots for the documentation related to finding and installing recipes using the Drupal CMS UI. These images will accompany text that was written about a month ago, and reviewed and updated last Thursday. It outlines the steps a user will need to follow in order to use the UI to navigate through a series of pages and forms. After capturing a couple of screenshots, I realized that what was in the images wasn’t matching with what was in the text.

In the four days that had passed since the text was written:

• The navigation path had changed from Extend > Browse > Recipes (sub-tab) to Extend > Recipes.
• Various page URLs had changed.
• The name of the button you use to choose a specific recipe in the browser changed from Select to Install.
• The installer previously allowed you to select multiple recipes to apply at the same time, but now you could only choose one.

This left me equal parts excited because the new UI is a big improvement, and frustrated because now I have to update the text and re-capture screenshots.

The project itself isn’t the only thing that’s evolving rapidly. Much of the supporting infrastructure is also a work-in-progress. Which means that some of that text is in Google Docs, some of it’s on Drupal.org, and some of it’s in both places and it’s not always clear which is the most up-to-date.

Have you heard the metaphor of changing the tires of a car while it’s driving down the road at 60 mph before? This definitely feels like that.

The pace of innovation is high …

I mean, look at this commit log! That’s an average of 7 commits a day since Thursday. And two of those days are the weekend! And, that includes what’s in the drupal_cms repo, not any of the dozens of contributed modules that are included in Drupal CMS which are also making rapid improvements. 🤯

Image

Drupal development has historically moved at a slower pace, focused on being deliberate and complete. Moving fast, one of the promises of Drupal CMS, requires different processes. And this introduces new and different pain points.

The reality is, creating high-quality accurate documentation for a moving target is super hard. And we’re constantly having to make decisions like, should I start this section now even though the feature isn’t committed? If I don’t start it now, there’s no way we’ll complete the content before launch. But, there’s also the possibility the feature gets cut, and now we’ve expended a bunch of time that could have been spent elsewhere.

The alternative of course would be to wait until code freeze, but in this case that would’ve only given us a couple days to author the documentation, with very little to show at launch.

So, as things stand today, we’ve got a partially complete (and up-to-date) guide, an outline that illustrates what we want to tackle next, and an even larger outline that represents what we think the ideal finished product looks like.

Personally, I’m really proud of what we’ve accomplished so far. And at the same time a little bummed, because it’s less exciting to release something that you know is incomplete.

Inside the black box …

If you’re feeling confused about what’s going on with regards to Drupal CMS documentation, what the process has been, how to get involved… you’re not alone.

Right now we’re at a point where we are simultaneously trying to figure out what these new pain points are and how to address them, while also trying to do the work to deliver on a tight deadline. It’s different from how we’re used to participating in open source projects, and it’s not very comfortable. Yet.

To illustrate, today's task list includes:

• Figure out how to allow others to contribute and make their ideas heard.
• Deliver best-in-class documentation ASAP.
• Uphold our part of the Adopt-A-Document promise.

All of which I’ve realistically only got a few hours a week to work on. And with the January 15th deadline looming, the writing has definitely taken the bulk of that time.

Figuring out how to allow others to contribute …

Contribution and collaboration in an open source project is challenging enough. Figuring out how to allow others to contribute to docs which we have been contracted to create is a brand new challenge. It’s challenging because it runs up against our values of transparency and open collaboration, which is uncomfortable. Here’s a situation I’ve recently been navigating: how can we enable the privacy and compliance team to contribute to documentation on the highly technical feature set they’ve developed for Drupal CMS? It’s an interesting challenge, mostly because we really appreciate the privacy and compliance team’s interest in ensuring great docs for their work, but we find ourselves in a new collaboration dynamic that none of us are used to! Here’s some insight into what I’m facing and how I’m navigating it:

• The folks working on the privacy and compliance work want to contribute to the guide on how to use these features they’ve built. This makes sense because the details of these features are complicated and need explanation.
• We have a contract to create the docs, but our process includes talking to the technical leads to understand the features.
• We had a priority list of docs to create for launch that didn’t include the privacy features (which may have been an oversight, to be honest).
• Solution: Invite the privacy and compliance track team to start collecting notes about what should be included in the docs for the features they’ve built, we’ll create the docs and screenshots, and then invite their feedback before it's published.

Not the usual, create an issue, comment on the issue for months (or years), and see what can be accomplished. More like: Privacy track team: "We have time to work on docs, where can we help?" Me: "Not sure because, I also don’t know … Communicates with docs and product leads… Yes, we need and welcome input, here’s a rough idea of the process we’ll use, but we’re not working on that right now… We’ll circle back after we catch our breaths post-launch." Not comfortable! But it’s the reality we’re in, and ultimately means high-quality docs on privacy and compliance will get done. Just not as soon as anyone would’ve liked.

I’m more used to the process we used to create the original Drupal User Guide which involved many months of creating and sharing a plan and getting feedback, creating and sharing an outline and getting feedback, drafting and sharing a process and getting feedback, and so on. We made sure to always give the broader community the opportunity to participate and give feedback (even though we ultimately didn’t get much). It felt like the right approach to open source documentation. The downside is that project took nearly 2 years to complete.

Drupalize.Me’s role in Drupal CMS documentation

At Drupalize.Me, our values include a commitment to working collaboratively. Which I interpret to include being transparent and creating space for others to engage in the work.

Drupalize.Me has a contract with the Drupal Association in which some of the funds raised from the Adopt-A-Document program go towards paying us to create the end-user-facing Drupal CMS Guide. At a high level, the Adopt-A-Document program allows someone to sponsor a section of the Drupal CMS Guide. These sections are based on a proposed outline that was created back before anyone really knew the exact details of what would or would not be part of Drupal CMS. And, like Drupal CMS, that outline continues to evolve. When you sponsor a section, that section gets put into the pipeline; when it’s published, you’ll get credit.

It’s a new approach to solving the long-standing problem of funding open source documentation. And the first time we at Drupalize.Me, the Drupal Association, or the Drupal community, have tried anything like this. And we’re all figuring it out as we go. I think the model has potential. But it is hard to really know until we have some time to stop and reflect.

What to expect on launch day... and beyond

On launch day (January 15, 2024), an initial set of documentation focused on getting folks started with Drupal CMS will be published on the new Drupal.org site. This is happening in the midst of a bunch of infrastructure changes on the new Drupal.org site, so expect some dust and changes to the guide after it’s initially published. This is just the beginning of the guide!

Moving forward, we’ll work with our documentation track lead at the D.A. (Lenny Moskalyk) and the Drupal CMS product lead (Pamela Barone) to make sure we’re agreed on the next set of documentation priorities. (The sections with Adopt-A-Document sponsorship pledges being the top priority.) Personally I'm excited to work more with the other Drupal CMS track leads to get their input and review of documentation we create. And with the D.A. to continue to evolve the underlying infrastructure.

What we don’t know yet – and it’s a question you probably also have – is how feedback on the guide will be collected and passed along, and how we’ll respond. While we have that process well-oiled for Drupalize.Me, this situation is different, and as a community we're still figuring out all of the pieces of that feedback machine. What we’re doing at the moment is creating the docs for the Drupal CMS guide. The publication process and feedback gathering and other infrastructure stuff is being worked on by the Drupal Association.

For the time being, my recommendation is to file an issue in the https://drupal.org/project/drupal_cms issue queue under the documentation component if you find any bugs, or have suggestions.

A challenge we're excited to face

Working on documentation for the fast-moving Drupal CMS open source product has been challenging and sometimes frustrating. But we've made significant progress and are super excited to continue the work. And to continue to stay true to our values of doing great work and working together. While it can be confusing and frustrating to navigate a new situation – one with deadlines, the horror! – we’re really proud of the first draft of the Drupal CMS guide, and the groundwork we've laid for future documentation. We hope that it will enable people to successfully build sites with Drupal CMS.