Complex of reasons
Drupal is one of the most powerful CMSs in the world. But it’s hardly a beginner-friendly CMS.
It offers a different concept of programming compared to conventionally used languages - bringing in a number of issues that makes this CMS even harder for beginner developers to deal with.
The community is important for Drupal evolution. If skilled developers want to expand this community, these issues must be fixed. If beginner developers want to be a part of the community and be more successful, they’d better speak up about the problems that make a learning process harder than it should be.
The first issue is in the documentation: some of the functions lack description or don't have a correct one. It’s an impactful and serious problem and it won’t be solved fast. There is a vast number of functions with extensive options and possibilities, but a lack of information in documentation basically hides them from an inexperienced coder.
One more problem is functionality. Sounds weird, but it is. There are a lot of possibilities. More than you can use. Some of the features have functionality that is significantly different from what stated in the documentation.
Let’s consider these aspects in details.
The first problem is the documentation being poorly detailed here and there. Let’s take a look at the following function as an example: MapperInterface::getInstance(array options).
What can one say about the parameter? It’s options, and it’s an array.
The documentation says:
“An array of options that can be used to determine a suitable plugin to instantiate and how to configure it”.
There’s no example of how to use it. There’s no info on what options can be applied here and how to use them. This documentation is not clear – it contains a generic text.
Another example is Plugin API. This is undetailed, too.
“But the problem with those, and all the examples I could find, was they were either too deep (the drupalize.me article should be considered required reading, but the example is too abstract for most people) or too shallow (the drupal.org Plugin API examples currently lack context about why I would want to do this in practice).” - says one drupaler.
Let’s see a good example for the sake of comparison: the MSDN function.
There you can read about the function all that you need:
- The parameter is a one-dimensional array.
- You see all kinds of possible exceptions.
- And this documentation has a code example.
Another good example is the PHP documentation. PHP is closer to Drupal then any other language.
If you want to write your code you need to know about possibilities of a selected tool.
This problem can be fixed by writing full and correct documentation pages with examples. There is a good documentation on Form API and not so good about Plugin API. Form API documentation is easier and more intuitive. First of all, there many examples of usage. Secondly, the documentation of Form API is very detailed. Thirdly, it’s good because there are many examples of using it in the core.
What can you do to make the documentation better? In my rather humble experience of a Drupal 8 beginner (I have 6 years of experience in development, though), everyone can do the following:
- Use the structure I proposed above: this way the documentation will have all the essential info that one needs for development.
- Don’t pass by if you see that something goes wrong in the documentation: comment it and submit the correct variant.
- Write more examples from your practice.
Anyway, if you have an idea what a standard documentation should look like, submit your idea on drupal.org!
A lot of efforts were invested into releasing the 8th version of Drupal. Yet, there is still a lot of work to be done.
Not all functions and classes work the way one would expect. For example, the Date field in Form API.
'#default_value' => array('year' => 2020, 'month' => 2, 'day' => 15,)
But if you try to use this code you won’t see your value in the field, you’ll see a NULL there.
You can try it another way like this:
$date = new DrupalDateTime('2012-12-31 12:30:00', 'UTC');
// Something code
It won’t work either.
Apparently, this is the proper way of using it:
'#default_value' => '2016-11-07',
You can’t set your value in the field any other way, but the documentation says otherwise and it is downright misleading.
Also, there’s no way to change the date format.
As it can be seen from the documentation of this function which is automatically constructed from source code comments, the Drupal core is not finished. If a product is still a work in progress then devs are expected to at least mention it in the documentation – that would somewhat be fair.
Fortunately, this problem has an issue and can be fixed in nearest releases.
It’s as easy as falling off of a log.
- Check code samples you insert into the documentation.
- Comment code.
- Fix the mistakes you see and leave a comment if something goes wrong. Like I did above. If there are some known issues it would be extremely helpful to list them in the docs to see it right here and right now. It will help you to code more efficiently and faster. If your code does not work, you can see that Drupal core doesn’t have an issue about it. And you can create the issue which will be fixed.
That`s all about functionality. You can look for other flaws yourself.
All these problems can slow down learning how to develop Drupal modules at present. It forces developers to look for other simpler areas. And this does not allow the community to expand as much as possible. It can be changed. You know about these problems. Our task is to change it.
Everything can be done in several months of work at most.
- Add examples for each function.
- Place reliable information on each documentation page, and list known issues on pages with info on functions that are known to have those.
- Write issues about documentation with correct examples to fix it faster.
- Write correct documentation by yourself and push it on drupal.org.
With all that being said, it's hard to deny all the possibilities provided by the Drupal CMS to a web developer. So it'll be delightful to see all the flaws fixed and this great tool being more beginner-friendly.
You can create issues about it on drupal.org. Once it is created, you can follow on this issue to show how it is important.
Let’s make Drupal more developer friendly.