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. 🤯
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.
