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?
But...
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.
Or die...
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!
Comments
At a minimum, every function parameter should be documented, and the return value as well. Unless an argument is self-apparent (like $uid or $content_id), I'll always include an example of a properly formatted variable or array structure in the docblock.
Also, if nothing else, include an @see in the doc block referencing something that explains what the function is doing, an issue on drupal.org, or some other form of documenation.
I usually write the docblock before I start on the code; it helps me to conceptualize what I'm doing a little better anyways.
Yes!
I recently spent nearly an entire week trying to figure out Notifications integration. At the end of the week I contributed back what I had learned and rewrote practically the entire developer documentation from scratch. Had my documentation been there when I started, it would have taken me probably 1 day instead of 4-5.
(Here's the beginning of the docs I wrote: http://drupal.org/node/1199556 )
So please, for the love of your fellow developers and their sanity -- document your code! And that means both giving descriptive comments in your code and for every function as well as explaining how to use the API on drupal.org.
Great article!
http://drupal.org/node/1093318#comment-4214286
That guy really doesn't get it. Who would want to work with him!
long on logic, short on actual suggestions.
I don't think anyone would disagree with anything you said.
And the one gem:
"Why couldn't we have a simpler web-based system for typing out docuementation?[sic]"
is relegated to only 1 sentence!
I agree, it would be awesome if everyone got in the habit of documenting as they go.
Though, I don't agree that Drupal core is well documented. The number of times I've been told to look at the examples module in order to figure something out proves it.
And trying to help document things is painful. I once tried to help get the global $user variable documented. Specifically, what the default contents are. So I was able to figure out some of it, but there were a bunch of array keys I had no idea about, so I documented what I knew, and noted what I didn't. The response? "This isn't ready for a patch. Get it right and I'll submit it." Which was obvious... And no one ever helped clarify the stuff I didn't get. See: http://drupal.org/node/630826
It's not like the information isn't out there. I just found it in Pro Drupal 7 Development. But I don't get why I had to get a book for something as central to Drupal as a Global variable.
Anyway, end the mini rant, and now for something hopefully constructive! :D
Maybe D.o could implement a git commit hook that says "Hey, you haven't added phpdoc for these (list of functions) functions, should I really commit this?"
No idea how hard it would be, but what about an api for contrib?
And maybe a "Create Documentation Issue" for all parts of the API's and Docs, so that we can easily help document things? Just click the link and an issue form is generated for you to fill out. With some kind of template in it to help get all the information documentation people need from the issue submitter. Or something like that.
Anyway, kinda rambling....
Absolutely agree. I also find it very useful to see a Bird's eye view of the whole workflow of a piece of code on top of the functions documentation
I wholeheartedly agree.
There are now 10,643 contributed modules! I would guess that around 75% of them have no documentation at all. When I'm looking at modules I start with two questions:
1. What is the objective.
2. How does this accomplish the objective.
Without any documentation, sometimes it's impossible to know.
Perhaps a more stringent vetting/review process is in order?
As someone who works heavily in contrib, I fear that the message of this post is lost in the fact that the people who most need to hear it are going to feel attacked. And when people feel attacked, they will respond negatively or not at all.
You would have served everyone a lot better with this message if you were more constructive. Provide people with solutions that aren't just "Work harder on your free contributions!"
As Drupal grows, we more and more forget that the people who are working in contrib are contributing their time and their code and doing this mostly out of the goodness of their hearts. Attacking them does not improve anything.
I have no idea if you're targeting me with your post or not, to be honest. There are always people constantly complaining about the level of documentation my code. So if it helps, I feel attacked, and probably every single developer in contrib, unless they've actually got some seriously beautiful documentation (there's one or two) are going to feel attacked by this.
If you're happy with your tone, so be it. But I think it's bad for the community, not good for the community.
To clarify: I have a longstanding weariness of people yelling at contributes to contribute more without constructive offers to help alongside it. That's how I read this post.
I have seen your code, read your book and perused your documentation. I think we can all agree that you are one of the best examples for all to follow.
I think the suggestion in the article to document and comment as you go is just programming 101. Trying to remember everything I did in the past is very difficult without taking notes (especially as I get older). This becomes even more critical if I am trying to collaborate with someone.
As for vetting, when my wife vets contributed code in the banking industry, the first part of the process is "What is the goal and how is this going to get you there". It can and should be a very positive and helpful process.
The suggestion to automatically start documentation is also quite helpful. It is a rare person who can both write well and code well. Some of us who write well but don't code well would love a mechanism to be able to contribute on that front a little more readily. Perhaps this could also help to elevate the discourse to be a little more constructive?
100% Agreed. LOL
Even I'm not developer, I noted everything I do with pen and paper along the way I'm building a site.
Why?
Simple, I'm not a smart man who can remembered zillion thing I have to deal with Drupal all the time. I don't want to repeat myself when I run in to that problem again.
Stack our knowledge up on top of each other is the way to go. This is my post:
http://drupal.org/node/1196526#comment-4703242
Which some part was take from this blog too.
And I think that my poor writing still be able to safe hours for many people, which is not bad at all.
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.
If you are reading an undocumented function in a Drupal module, then you're probably a Drupal developer, and using git and making patches comes naturally to you.
See what I did there? ;)
Your post managed to ignore the point that many of the documentation improvements to Drupal core in recent years were not the result of people writing code adding lots of documentation at the same time (although that has definitely got better). What mainly happened is people find errors and omissions in documentation, then post patches to improve them.
Also even with new code, docs (and automated tests etc.) are not always added by the main patch author but by multiple different contributors via the process of review.
A lot of contrib projects do not have multiple authors and long tail contributors in the same way, but that is partly due to the same us-and-them attitude that comes through from this blog post.
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.
The original author of the code is not the sole person responsible for the 500 hours wasted though. If the first person to read that undocumented code takes a stab at documenting it and provides a patch, then that could save all the rest of the time for the next 999 people.
hmm, blockquote tags got stripped, the first and penultimate paragraphs should be quotes.
Appreciate the comments, and I do see what you're saying. I'd have to disagree and say if you're reading PHPdoc comments you're not necessarily familiar with git. I don't honestly know what proportion of API users are not git-aware, but it'd be an interesting one to find out, via a survey or something.
I also have to disagree with your assertion that the original author of the code is not solely responsible for the wasted time. I think the author is the only one who could possibly be responsible for that. Whether someone is kind enough to help out and provide documentation is a big factor too, as you say, and it would be tempting to say that if you're not doing that, you're compounding the issue.
I'd have to disagree and say if you're reading PHPdoc comments you're not necessarily familiar with git.
Drupal.org only moved to git a few months ago, a lot of developers use GUIs for it - again there is not necessarily any distinction here at all between the author and the reader of the code in terms of knowledge or skill level. If people can't use git to roll a patch, they're capable of writing up an issue and pasting suggestions in as text.
I also have to disagree with your assertion that the original author of the code is not solely responsible for the wasted time. I think the author is the only one who could possibly be responsible for that.
Drupal core has a lot of bugs in it. When you run into those bugs, are all the people who worked on core during thousands of hours of their free time wasting your time and solely responsible for this fact, or might you possibly have saved quite a bit of time via using Drupal up to that point?
Rather than the usual reasons to contribute back to open source, you apparently think people do so because they're "kind and helpful".
So I can only assume that you wouldn't do a thorough search of the queue, wouldn't take the time to post a meaningful bug report, and wouldn't bother getting a meaningful fix in place in patch form - because all of these are 'wasting your time' aren't they? Or if you did so, it'd only be out of the kindness of your own heart, rather than being the central mechanism by which the software that you are using and making money out of gets built in the first place.
This counts for functional bugs as much as it counts for documentation deficiencies.
The problem with this post, and many of the comments (and many interactions on Drupal.org itself), is that it is written from the point of view of a consumer.
Not only this, but this is a commercial website for a firm that is making money using Drupal core and contrib modules. What you are doing is berating volunteers to do morefree work, that you can then use to increase profit margins (whether yours directly or those of clients).
The questions that should be asked here are "how many patches did you review recently?", "how many documentation patches did you provide recently" these questions were neither asked nor answered by the blog post nor your followups.
I completely agree. Right now I'm wishing that views had some detailed api documentation and/or example code
I have to agree with merlinofchaos here, the tone is pretty inappropriate... particularly "The final factor is one of selfishness"
You start with targeting Rules module...
do you know how many projects those folks maintain???
And how many of their modules have already been ported to Drupal 7???
And how many of their issue queues are regularly attended to, with them answering issues promptly???
They do what they can for the project (which is a whole hell of a lot)... if there is somewhere that their time or abilities are lacking, that's where community needs to come together to pitch in.
I totally agree that things are to some extent broken, but you are placing the blame at the feet of the wrong folks.
Actually I am of the mind that modules should not be listed that don't meet minimum requirements. The people that promote Drupal love to talk about the ten thousand modules but truly how many can you use without pulling your hair out. For example to be accepted a module must have readme with:
1. List module dependencies.
2. Show setup screen with options explained or list the options with choices and what choices mean.
3. List known constraints.
Well you get idea. For starters if you can't load and go with a module and it doesn't have docs to assist why should it be on the list of modules. Now there may be a second list - sort of a B list for those of you who defend this sort of sloppy development(you know it's free) and those of us who don't mind the time sink- there may be room for all without attack/defense thing that seems to happen.
Just a few thoughts.
Let me get this right, 'What we as a community can do' about this problem is to yell at the developers and tell them to do more? Or blacklist their modules? Or maybe we should just kill them (Document or die)?
I was actually hoping this article would suggest getting other people involved to help improve documentation, but no, it's just another rant that developers don't do enough.
The people who write these modules have to write the modules, test them, deal with bugs in the issue queue and fix them, deal with support questions in the issue queue and answer them, deal with feature requests in the issue queue and explain why everything that everyone wants can *not* be added. And most of them are doing this (for free!) for multiple modules, not just one. And the only reason you can think of why they didn't document the code better is because they are lazy?
I find it strange that developers can find the time to write modules, test them, deal with bugs, fix them, deal with support questions, feature requests and so on, yet cannot find time to do the fundamental task of documenting clearly what their module does. How ironic!
I wonder how you don't call that an attitude problem.
Spoken like a true non contributor. Bravo for making her point.
As a matter of fact, I have contibuted to several doc pages over the years and also maintain a contrib module or two. I am just not an uncritical fan boy.
Then why post 'anonymous'? Why not put your tracker where you opinion is.
And it's not a matter of fan boyism, it's a matter of appropriateness and entitlement.
I'm not sure what enables this behavior-- the nature of open source or the anonymity afforded by the forums and issue queues.
Here's a lesson in entitlement--
when someone volunteers their time and energy to something, you are not entitled to tell them how to do it. Period.
If someone walked up to you and handed you $20 for no reason, would you whine to their face about how it's not enough and you need $100?
If someone volunteers for a church function, or donates money to a cause, would you whine in their face about how it's not enough or how they should do it to meet your needs?
How is this any different? Actually it's worse, because many of those doing the whining are making a living off drupal, contributing little to nothing back, and complaining about what their getting for free. In any other context it wouldn't even be a debate-- it would be considered extemely poor behavior.
And for the record, it case it's still unclear. No, you are not entitled to tell me how to spend my volunteer time.
How much extra time would developers have if most questions were answered in the documentation? I know that a lot of the issues I've posted, or posted in, would never have come up if I could have found my answers in the docs.
So, I greatly appreciate how much work devs do, and would love to contribute myself, but the lack of documentation seriously gets in the way.
It's pretty hard to solve an issue when you have to rewrite the module in your head in order to understand it. It would be much better to be able to read docs that explain things, then be able to fix the issue based on that knowledge.
So, I'd rather devs produce less code, and have what they produce be more useful to me due to the good documentation.
As I was walking home today, I thought of an interesting analogy... it's like there's two roommates, Alex and Bart. Alex takes the initiative to wash the dishes every day and doesn't ask Bart to help. Because there's just one of them, he puts the dishes on the dishrack to dry. One day, Bart turns to Alex as he's washing the dishes and says "You know, you really should wipe those dry before you put them on the dishrack, because otherwise they get spots". Bart is totally correct... but he's not right. The right thing to do would be to say "Hey, I'll dry those".
We simply can't hold the high-output contributors to a different standard than we hold ourselves. It seems most of the people who have been commenting here about how devs don't do enough, or how devs should restructure their time, simply aren't holding themselves to the same standard.
For those who have commented here about how other people should act, please consider whether you are acting in accordance with your own suggestions.
Even if you aren't a dev, you can be just as prolific a contributor:
- 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.
If you *are* a dev, you have no excuse. If you are too busy making money from building sites by using someone else's code that you don't have time to help them improve that code... well, I don't think I need to point out the issue there.
It seems to me that the energy that goes into posts of this nature (as well as the comments) is misguided energy. Had that energy been used to solve the problems, there would be no need for posts like this to exist.
Those who aren't part of the solution are indeed part of the problem.
Why don't YOU sit and document ? As Earl said, ANYONE can write documentation.
We have too many complainers and too few people that actually do something.
Besides that, I find the the article title and it's tone inappropriate and insulting. People writing free software don't owe anything to you, therefore such attitude is unacceptable.
"Code contributors could do more, despite some arguing that they do enough already, and I've no doubt they do. People using the code could also do more, and I think the focus there would be making it as easy as possible for them."
Not quite-- there are far more people, most of them making money, contributing little to NOTHING that MUST do more than there are developers with extra time to try and contribute yet even more.
This is a fundamentally unfair division of work and ignoring it or belittling the problem is disingenuous at best.
And it's not just limited to modules. I can't tell you how many times in the forums the people I'm helping for free, who contribute nothing, complain about the assistance I'm rendering. It's mind boggling.
I don't spend enough time in other open source projects to know if it's a drupal specifi thing or and open source thing but it's insanely frustrating.
And posts like this only serve to poke the do-bees in the eye yet one more time.
How about some posts illuminating the enormous gap between the do-bees and the non-contributors? How about throwing a little guilt at those that make a living off drupal and contribute zero?
Being a small do-bee that's hoping to do more, I would like to point out the Praire Initiave that intend to :
1. Improve the collaboration tools on Drupal.org so that we can do more and better work together and make Drupal better, faster.
2. Grow the pool of contributors by making Drupal.org a better and easier place to become a contributor - to make it less intimidating to people who want to get started contributing.
That includes writing more and better documentation, growing number of people who writes it, facilitating the process of doing so. The Praire Initiative is THE big chance we as a community have to organize and actually do something about it. The web is full of designers and tools to do smart changes on websites : creativity, a-b testing, user testing like those who recently happened, analytics etc. We're a community of "web people", let's treat our own site as any others we work on and do our job/passion/best to help.
People are appreciative of the vast amounts of time put in free of charge by Drupal contributors
Really? Because the tone of this blog post is coming off as the exact opposite. It sounds demanding and entitled.
The vast majority of people that have released code, documentation, designs, etc. on Drupal.org are attempting to give something back to the community. They are real people with various demands on their time: family, kids, job, community associations, and the people that use their contributions. Time is limited and contributors have to balance these demands. By spending more time on their contributions, time needs to be taken from somewhere else. So priorities must be made. What is important sometimes gets sacrificed for what is urgent. Documentation sometimes gets sacrificed for getting the paying client (as opposed to those that use their contributions for free) a functional product. Until there are more hours in a day those sacrifices are perfectly justified.
In my opinion this blog post should simply be unpublished.
Community driven projects are driven by the community no? How can you hope to allow others to contribute patches, or help improve code when it is completely uncommented? When the only person who has a hope of understanding it is the original author, it may as well be closed source.
It goes against the grain of how open source should work, what's more it will likely save the original contributor huge amounts of time by having others do the work for them. Is that not what it is all about?
I also think Drupal is not well documented - it's supposed to be easy to understand but of course when you find a great module / add-on that someone's coded - you only need to try to install it to see you basically need a one on one consultation with them to get it up and running - or at least know how they wrote the code - which of course defeats the point.... Great tool but a long way to go...
A good discussion on a worthwhile topic!
Incidentally, Chris, the article contains several misspellings: docuemntation, mystefied, excecllent, insulte. FYI.
You mentioned, "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." That is true. But if you write documentation as you are writing the code, it's easy to fall into the trap of assuming that the reader understands the context, which you the programmer naturally understand at that moment. Perhaps the ideal approach is to write those initial comments, at a minimum, and later return to the code, to see if those comments still makes sense to you and fully explain everything to someone unfamiliar with the code. Writers use a similar "cooling off" technique when revising their own work.
As for your point that "Why should someone have to use version control to submit a doc patch?", there have been countless times when I've seen errors in the documentation of contrib modules, and would have been happy to immediately submit fixes, had there been a simple and quick way to do so.
