Part of being successful with any system is knowing the strengths and weaknesses surrounding its use. As Drupal developers, we frequently immerse ourselves with the strengths; after all, the size of the community and the code it unselfishly provides to others is monumental in of itself. But with as much zeal as we throw toward the things Drupal does well, we should be providing equal focus to the areas where it needs improvement.
Especially those areas which don't involve code.
The Drupal community has done a fantastic job of producing a robust and extremely powerful product with a set of equally powerful tools at their disposal, but an escalating trend of high-level focused documentation and market-perceived barriers to entry renders those tools all but lost to the average user - and that's a trend that needs to stop.
It begins within
Those of us immersed in Drupal as part of our daily lives are at the front line in responsibility to furthering the notion that the Drupal software suite and module collection is easy to use despite frequent feedback that says otherwise.
One of the biggest strengths to Drupal is the community, but contributions shouldn't be limited to just code samples. Myself included, we must embrace a focus on shifting Drupal's front-facing documentation from a developer and tech-focused audience, to more of a general purpose audience adoption. This is not a core-maintainer focus either, to truly succeed such an endeavor must be embraced by the entire community, down to each and every maintainer and contributor. To truly succeed, the entire community, down to each and every maintainer and contributor, must embrace such an endeavor.
Picking on the best
Taking a look at a few of the most popular Drupal modules lifted straight from the project usage top 10 list, can highlight areas where documentation could be improved for wider adoption.
Should be noted: No mention of these modules' code nor critiques of functionality wil be mentioned. This is not a code review but a focus on their front-facing aspect and initial impressions. These fantastic modules are built and maintained by some extremely talented and smart individuals.
Features
What is the Features module?
According to the project page, "The features module enables the capture and management of features in Drupal. A feature is a collection of Drupal entities which taken together satisfy a certain use-case."
Developers among us understood what it means, and we know just exactly how much of a time saver and useful module this project is - a completely fantastic and borderline required module for any project.
But this is a highly technical overview, aimed at adoption among power Drupal users. Is there anything wrong with this? Absolutely not, but it can't be the only entry point for user-based adoption especially given just how powerful and useful the Features module set is.
While such requirements for documentation might seem unfair on the surface for Features, as it's unlikely a common user would need to utilize this module to its full extent, the end result is only those with the prowess of such Drupal-heavy technical expertise end up understanding the extreme benefits and just what a timesaver this module provides. Everyone involved in such decisions regarding a Drupal deployment and choice should be aware of the benefits of using this module.
It could be the deciding factor between a Drupal deployment or some other CMS.
Views
The Views module is arguably one of the most 'required' of the non-core Drupal modules. This is an absolutely fantastic module that deserves every bit of praise we can throw its way. That being said:
"The Views module provides a flexible method for Drupal site designers to control how lists and tables of content (nodes in Views 1, almost anything in Views 2) are presented. Traditionally, Drupal has hard-coded most of this, particularly in how taxonomy and tracker lists are formatted.
This tool is essentially a smart query builder that, given enough information, can build the proper query, execute it, and display the results. It has four modes, plus a special mode, and provides an impressive amount of functionality from these modes."
One of the most brilliant and important aspects regarding Views is that it completely eliminates the need for custom database queries constructed by a developer, yet in the second paragraph of the description we see continual references to building queries. A minor point at first glance, but taken through the eyes of the average user the module can appear to be too high level and beyond the technical capabilities for basic site building. This couldn't be further from the truth. Views is such a powerful and fantastic module it should be a baseline requirement for any Drupal site build and a user should be able to judge this and strive to use the module regardless of technical expertise.
Should this be changed? This depends upon what type of audience the Drupal project page is aimed toward. If such documentation is to be relegated only to the developers among us, descriptions as seen here could be considered sufficient. However developers are not the only people reading these pages, and the task of constructing documentation for consumption across multiple entry points is extremely complex.
Where to go from here
The Drupal community is, for the most part, a volunteer community that contributes code and modules because many find it enjoyable. It's what makes the product such a fantastic one and the potential so strong. The perception of a high barrier to entry is just so much my problem as it is anyone who reads this.
In fact many might argue my time would have better been spent doing as such instead of crafting this block. And I would not argue with that. But a more user-friendly approach has to be taken on behalf of the entire system, starting at Drupal.org, down to core, into the interface design and finally out to the modules and contributed source.
As proud as we are regarding the powerful and vast module contributions to Drupal, the next step should be attempting to be equally as proud of the lower barriers to entry and ease of use for those picking up Drupal for the first time.
The best approach for me is to now lead by example.