Drupal's documentation is terrible. I'm not talking about Drupal core. I think leaps and bounds have been made there over recent years, although there is still more to do. I am pointing the finger directly at Drupal contributed modules. What sort of state are things in? Why are they in such a state? What can we do as a community to improve things?
UPDATE: thanks to all the commenters for creating a lively discussion. One of the main criticisms of this post was that it did not do enough to suggest improvements, so I have added a new section beneath suggesting ways forward. I have also added the 'I'm writing free software so you must automatically be grateful' case to the list of common reasons for poor documentation.
Contrib is bad
Here's an example for you: rule(), which is part of the rules module, whose documentation is at http://drupalcontrib.org/api/drupal/contributions--rules--rules.module/function/rule/7. It states:
"The array has to be keyed by variable name and contain a sub-array for each variable that has the same structure as the arrays used for describing parameters of an action."
The problem is that this just doesn't mean anything to someone who doesn't already intimately know rules. Compare this with the documentation from Drupal core's l() function, at http://api.drupal.org/api/drupal/includes--common.inc/function/l/7:
"$path The internal path or external URL being linked to, such as "node/34" or "http://example.com/foo". After the url() function is called to construct the URL from $path and $options, the resulting URL is passed through check_plain() before it is inserted into the HTML anchor tag, to ensure well-formed HTML. See url() for more information and notes."
The parameter is explained in detail. It is not necessary to understand the concepts of 'internal' and 'external' paths to understand how to use the $path parameter, because examples are given. Enough information is given here that someone fairly new to Drupal can understand what to give as the $path parameter.
There are plenty of other places in contrib where the documentation is incomplete, confusing, or simply missing altogether.
Why are things so bad?
Drupal has had a legacy of a steep learning curve, and this is partly due to poor documentation in the past. Drupal's own core documentation was poor for years, and has recently been vastly improved. However, existing Drupal developers who were around in the poor documentation days, and 'grew up' thinking that 'if Drupal core has poor documentation, I can have it too' are still around today, in great numbers.
It is far easier to just type code than type documentation at the same time. After all, I understand this code, and that's all that really matters. I'll just go back and add proper docuemntation when the module gets to release. Nobody will mind that. Right? Completely wrong.
Another factor is the sheer difficulty of writing good documentation. The kind of person who writes properly functional code is the kind of person who understands things quickly, takes leaps of faith based on existing patterns and design practices, and takes a lot of complex concepts for granted. That same person is naturally not going to be good at explaining things to others, which means only a limited number of people will have an innate ability for writing good documentation.
The final factor is one of selfishness: I am the one writing the code, and I understand it, so I don't really care if someone else is mystefied by it, because they're over there, and not over here: it doesn't affect me. We need to get past this as a community. Even if I'm not affected by this single piece of poor documentation, if everyone is adhering to the same selfish practice, I'm going to come across someone else's selfishness at some point.
Why should I care?
A very good question to ask. Most Drupal developers are working on code that will be used on the site they're working on, and never seen again, or committed to the community. Those that do commit to the community might be working on their own code, and might be unwilling to do things properly, as I have encountered many times.
Consider the impact of an undocumented function. What happens when you need to use it, but there are no docs? You read the code and attempt to understand what it does. You call the function a few times, trial and error style, hoping for the right result. Or, you might step through the code to understand how it works. Imagine it took you 30 minutes to get there. No big deal, right? Now imagine 1000 other developers in your situation. Suddenly you have 500 hours of time that could have been put to better use if the documentation had been put in place in the initial implementation. Consider it might take 30 minutes to write the docs. That's a saving of 499.5 hours.
That saving is made by the community itself. In not writing documentation, or writing poor documentation, you are effectively causing time to be wasted. That time could have been used by fellow developers to better Drupal sites, or contribute more code or tests to core, or write better contrib modules, or write their own documentation more completely... well, you get the idea.
The net result of poor documentation practices is a community that gets held back instead of flourishing. There are thousands of questions on Drupal Answers. I have no doubt that the site would still have questions even if all documentation was perfect, but have you ever wondered how many of those questions would never have been asked if the proper docs had been in place?
There are no buts. Excuses are just irrelevant in this situation, but let's try to address some of the more common ones (a subject which has been approached many times in the past, inside and outside of the Drupal world):
- I'll go back and document it later. The chances are, you won't. Even if you do, you won't be 'in the moment' with that particular piece of code, not like when you wrote it, so your documentation is likely to be worse.
- This code is only for me. How do you know that? Suppose someone else takes over the site later, or you decide to contribute the module back to the community. Even if you don't, you yourself will need the documentation. You think you'll be able to remember why this variable was passed by reference a year after you wrote the code?
- Documentation takes forever. Yes, it takes time to write quality documentation. This time should be part of your build process, not an added extra. Deal with it. You're a grown-up.
- I'm no good at writing documentation. That's a shame, it really is. You were no good at writing PHP at one stage, and now look at you. You only get better at something if you do it repeatedly, so while your initial documentation might be flaky, it will definitely improve with time, as well as becoming more natural to write.
- My English is not so good, so people will be confused. Yes, but someone confused by poor English is likely to be less confused than someone who has no documentation at all. As long as you convey the ideas behind your code, that's the main thing. People will find a way to understand. Besides, your English will get better.
- I am writing software for free, so I'm doing everyone a favour. You should be writing documentation for me instead of moaning. This one does come up a lot, and is particularly disappointing. Free software doesn't have to be poor software. I see writing documentation as an obligation to which one does not receive a 'get out of jail free' card if one is working for free. People are appreciative of the vast amounts of time put in free of charge by Drupal contributors and I think that's evidenced by the prolific adoption of Drupal and the use of these freely available modules, yet unless documentation is excecllent across the board, the community should not stop on the drive to improving it, whether that's an improvement by someone using the module, or by the person writing it.
I'm sure there are loads more reasons not to write documentation. Any more? Do use the comment form!
Where do we go from here?
Doing things 'the Drupal way' is a term that means doing things right, in the way Drupal intended. Use sensible variable names, don't hack core, use existing modules instead of writing your own, and the list goes on. I think 'the Drupal way' should include:
"Write documentation as you write the code. If you have written a function and you move to the next without writing the documentation, stop what you're doing and reconsider. The documentation should be thorough, so someone with no understanding of your module can grasp what the function does, but not so thorough as to explain how PHP works or how Drupal core works."
This should be part of the Drupal philosophy. As a community, we could force people to write documentation, refusing to accept contributed code with no documentation, or some similar measure. I believe this is the wrong approach, and people should be in the habit of writing documentation because it's part of the Drupal philosophy, not because they have to. After all, it will produce better documentation that way.
Also, let's make it easier to document things. Currently, if I come across a contrib module that has no documentation for a given function, I have to install git, clone the module, write the documentation, submit a patch, and hope it's accepted. You might be thinking that's actually quite a simple process, but then you're probably a Drupal developer, and using git and making patches comes naturally to you.
Why should someone have to use version control to submit a doc patch? Why couldn't we have a simpler web-based system for typing out docuementation? Lowering the barriers to writing documentation will improve the documentation. As I mentioned earlier, the kind of person who writes good documentation is not necesarily the kind of person who is going to be knee-deep in code all day, and many people would be put off from contributing documentation back to existing modules due to the technical requirements.
What can I do?
Thanks to the commenters who suggested ways in which one can help out with docuementation.
- Write an overview of the function in the PHPdoc at the top. It should present a bird's eye view of what the function achieves and how it goes about it. It should not explain how PHP or Drupal core works.
- Follow coding standards to the letter whether you want to or not. If you hate coding standards, be mature and discuss changes with the community instead of simply rebelling. Use the coder module to review all your code. If people are reading code in an unfamiliar style, it makes interpreting the code harder, and more confusing.
- For each 'chunk' of code, a quick comment to clarify what the chunk does, and why.
- Do all of the above as you write the code, not afterwards. It will be fresher in your mind and you will be less likely to forget, or write something inaccurate.
If you're not a developer, but still keen to help out, Lin Clark points out that you can:
- Join the Views Bug Squad and to help answer simple user questions and sort more complicated ones.
- Review the modules in Examples for Developers projects and post bugs for anything that is unclear.
- Join the Documentation Team (non-devs wanted!) : http://groups.drupal.org/documentation-team.
This was obviously hyperbole intended to invoke an emotional response in you so you'd read the article! But, in a sense, it does hold some truth. Imagine a community where nobody wrote documentation. Nobody understood anyone else's code. It was far easier to write your own code than try to understand others'. The community begins to insulte itself, and eventually dies out. An extreme perspective, but it's already happening in small pockets within the community. Let's stop it from happening further and just agree to do things properly in the first place!
Has your time been wasted by poor documentation? Are you guilty of writing poor documentation but feel you have justification for it? Do talk to us in the comments!