Enhancing Drupal Experience: A Look into the Documentation and Help Initiative
In the bustling world of Drupal, where developers, evaluators, and site builders come together, one initiative stands out for its dedication to improving user experience: the Documentation and Help initiative. This project aims to enhance Drupal.org's documentation and implement a new topic-based help system within the application. Spearheaded by Joe Shindelar and co-maintained by a team including Amber Matz, Andrey Postnikov, Lindsey Kopacz, Shannon Vettes, and Matthew Grasmick, this initiative remains a vital part of the community's efforts.
Originally envisioned by Jennifer Hodgdon, the initiative thrives under new leadership. A key contributor, Amber Matz, recently shared insights with Kazima Abbas, sub-editor of The Drop Times, shedding light on the initiative's goals and recent updates to Drupal.org's documentation page.
Amber Matz primarily focuses on Help Topics (now part of the Help module) and the User Guide, serving as a co-maintainer for both projects. When asked about the Documentation and Help initiative, she elaborated on its inception and goals:
"The Documentation and Help community initiative was created to organize 3 major community-led projects: Help Topics in Core, the Contributor Guide, and the User Guide. It was originally proposed by Jennifer Hodgdon, who has since retired from Drupal community work. All 3 projects have reached their goals and are now in the maintenance and improvement stage."
Sharing the latest updates, she provided an insightful overview of the significant strides made in recent releases:
"As of Drupal 10.2.0, the Help Topics module has been integrated into the core Help module. On a Drupal 10.2.x site, go to the main Help page where you can see a new section called Topics. “Top-level” topics are listed here. Select a topic to read it, and to access related topics.
You can contribute topics to modules you maintain or use. I wrote up an example on how to do this in a Drupal Advent Calendar article back in December 2023. I used the Help Topics Standards documentation as a guide."
Amber continued, shedding light on the contributions of the Contributor Guide and User Guide to the Drupal ecosystem:
"The Contributor Guide is a robust guide for new and existing contributors. It is updated on a regular basis with new and updated information. It is an essential resource for mentors at DrupalCon and other community events, who are guiding new contributors to tasks that match their skills. I encourage long-time contributors to periodically follow along with task pages as they contribute, and update steps as needed."
Amber mentioned that the User Guide remains an indispensable resource for newcomers to Drupal, offering comprehensive guidance on on-site building and administration. Led by primary maintainer Joe Shindelar, the User Guide is continuously updated for each major version and adapts to the evolving needs of the community. Amber also highlighted Joe's recent article, 'Updating the User Guide for Drupal 10,' which provides valuable insights into the ongoing enhancements of this essential resource.
Amber highlighted the significant contributions of key individuals and teams to Drupal's documentation and guidance. Jennifer Hodgdon (jhodgdon), recognized as the original organizer of pivotal projects, played a crucial role in mentoring new leaders before retiring from active involvement. Joe Shindelar (eojthebrave) maintains and updates the Drupal User Guide, ensuring it remains current with the latest major versions of Drupal. Andrey Postnikov (andypost) significantly enhanced user assistance by integrating Help Topics into the core Help module. Amber also expressed appreciation for the dedicated mentors who tirelessly work to improve the effectiveness of the Contributor Guide, particularly during contribution events like DrupalCons.
Additionally, translators of the User Guide have made invaluable contributions by providing translations in 12 languages. These translations can be accessed via the sidebar of the Drupal User Guide HTML version, with maintainers of each translation listed on the Drupal User Guide’s project page. Their efforts have helped make the User Guide accessible to a broader audience, fostering inclusivity within the Drupal community.
Despite its significance, Amber pointed out that the Documentation and Help initiative page hadn't received updates since 2021. However, upon her recent update, there was a sense of celebration, as all three projects under the initiative had achieved their primary objectives, contributing significantly to the community's learning and contributions. Despite these accomplishments, Amber emphasized that ongoing attention and support are crucial for the projects, which still require updates and improvements. Information on contributing to these efforts can be found on the initiative's page.
We were also curious about any upcoming plans or features the community can look forward to. Amber highlighted a few upcoming plans and features for the community to look forward to:
"For the Help module, the plan now is to deprecate hook_help(). See #3031642 in the core Drupal project issue queue if you’re interested in following that issue. Search the Drupal project issue for keywords, "topic", using the component, "help.module" to find issues related to improving Help topics."
She continued,
"For the Contributor Guide, there are still some remaining issues to create content for this guide. See #3137918 in the Drupal.org/Community section issue queue and check out the remaining open child issues in the sidebar."
Amber further added,
"For the User Guide, Joe and I are planning on recording new videos for the guide as needed. (We originally did this with the support and sponsorship of Drupalize.Me, and have re-recorded videos over the years.) Check out the User Guide project page and its issue queue to help with issues or translations."
Amber also addressed the challenges faced during the initiative and how they were addressed. Each project has taken years to complete and is still actively maintained and used by the community, showcasing the persistence and dedication of all contributors.
Using Help Topics as an example, it took many years and two major versions (8, 9, and finally, 10.2) to integrate it into the core Help module as a stable feature. While setbacks were discouraging, Amber acknowledges the invaluable mentorship and feedback from core maintainers and release managers. Their leadership, encouragement, and guidance were instrumental in making this contribution possible.
Amber emphasizes the importance of maintaining a learner's mindset during setbacks, learning from the process, and expressing gratitude for the enlightening journey.
In the scope of the documentation and help initiative, it's crucial to highlight the opportunity for individuals to contribute to enhancing the User Guide. Joe Shindelar, the current maintainer of the User Guide, emphasized the significance of updating translations for the guide. Those keen on assisting with User Guide translations are encouraged to contact Joe directly. He can be contacted on Drupal.org using the username eojthebrave.
In conclusion, the Documentation and Help initiative reflects the collaborative efforts and dedication of the Drupal community. Through the contributions of individuals like Amber Matz and others, significant progress has been made in enhancing the Drupal experience with improved documentation and assistance systems. Despite challenges, their commitment ensures the ongoing success of these projects. We thank all contributors for their valuable input, and we especially appreciate Amber Matz's support and insights throughout this endeavor.