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: 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. 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. 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: 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. 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: 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. 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. 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.) We’ll continue to work with Drupal CMS track leads to get their input and review of documentation we create. And the D.A. will publish the docs we deliver. 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 to us, and how we’ll respond. While we have that process well-oiled for Drupalize.Me, this situation is a lot different, and we’re not in control of all (or really any!) of the pieces of that feedback machine. “All” we’re doing is creating the docs for the Drupal CMS guide. The publication and feedback gathering for it is in the hands of the Drupal Association. Working on documentation for the fast-moving Drupal CMS open source product as a contractor is a challenging and sometimes frustrating process. We want you to know that we’re excited and honored to be tasked with this responsibility, and we’re committed to staying 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 hopeful that Drupal CMS will have great documentation that will enable people to successfully build sites with Drupal CMS. Posted on Tue, 01/14/2025 - 20:34 by phenaproxima (not verified) Joe, you and everyone else involved in docs have been nothing short of heroic. I can't overstate how impressed I was by what I saw. This first version of Drupal CMS truly was built in record time, and there was a lot of ad-hoc inventing of processes, shifting needs, figuring out governance and communication, etc. That's still true, but I'm hopeful that things are going to slow down a little from here; new feature development will continue in the 1.x (development) branch, which will continue to move quickly, but the 1.0.x (release) branch will move more slowly and focus mainly on bug fixes, so I hope you'll have a chance to catch your breath and round out the extremely solid start your track has already made. Posted on Tue, 01/14/2025 - 23:37 by BatmansByte This may work out for the best. Screen shots are boring anyway, and while they're easy to follow, they're hard to remember as a sequence of screenshots. Instead, you can focus on the functional aspects of Drupal and how they fit together. A specific feature is probably somewhere in such and such a menu, it basically looks like ..., look around and you'll find it. Instead of trying to explain Drupal to five-year olds, try to help somebody on the phone, where you can't see their screen, implement a feature. Then when that's done and Drupal stabilizes (however briefly), add a little more detail to your directions, in such and such a menu, etc. Drupalize.Me is the best resource for learning Drupal online. We have an extensive library covering multiple versions of Drupal and we are the most accurate and up-to-date Drupal resource. Learn more
Sign up for our mailing list to get Drupal tips and tricks in your inbox!
Drupalize.Me is a service of Osio Labs, © 2025