[drupal-devel] A little about my morning. - Rant on Documentation
Hello, I had a fun morning. When I got up this morning I had an email from a client with a problem with the ecommerce module which was not sending out the email alerts to customers. In the end it turned out to be a problem with the payment gateway that I had developed for him. So here I am investigating/programming and fixing his problem before I could leave to go to another client, so doing some creative thinking and find the solution as fast as possible. This got me to thinking, and the main reason that this problem occured in the first place. Basically the problem was that "Documentation for contributed modules sux" (I am not singling out the ecommerce module, AFAIK it all sux). Basically I feel the problem is that there is no place for development/user/admin documention on drupal.org/drupaldoc.org for any of the docuementation that relates to the contributed modules. If there was something like this then the fact that the payment gateway module is required to call the functions to send the emails and may not have been making up a solution to a problem that I didn't know about on the fly. For a start I think that it would be good to have drupaldoc.org include all the documentation from the contributed modules. I know that a lot do not have the the phpdoc comments (I know that mine do not, but I would fix this if it is going to be used). Then maybe adding sections to the user and admin sections of the handbook so that the contributed modules can build documentation. This also means that people who cannot program or contrbute modules can contribute by writing documentation much like we do now for the core documentation. Just my thoughts. Gordon.
There is a place now in the new handbook for contributed module information. :) To contribute, use the docs list. Anisa. Gordon Heydon wrote:
Hello,
I had a fun morning. When I got up this morning I had an email from a client with a problem with the ecommerce module which was not sending out the email alerts to customers. In the end it turned out to be a problem with the payment gateway that I had developed for him. So here I am investigating/programming and fixing his problem before I could leave to go to another client, so doing some creative thinking and find the solution as fast as possible.
This got me to thinking, and the main reason that this problem occured in the first place. Basically the problem was that "Documentation for contributed modules sux" (I am not singling out the ecommerce module, AFAIK it all sux).
Basically I feel the problem is that there is no place for development/user/admin documention on drupal.org/drupaldoc.org for any of the docuementation that relates to the contributed modules. If there was something like this then the fact that the payment gateway module is required to call the functions to send the emails and may not have been making up a solution to a problem that I didn't know about on the fly.
For a start I think that it would be good to have drupaldoc.org include all the documentation from the contributed modules. I know that a lot do not have the the phpdoc comments (I know that mine do not, but I would fix this if it is going to be used).
Then maybe adding sections to the user and admin sections of the handbook so that the contributed modules can build documentation. This also means that people who cannot program or contrbute modules can contribute by writing documentation much like we do now for the core documentation.
Just my thoughts. Gordon.
Hello, Thanks for the pointer, but being a developer the biggest beef I have is the fact the the drupaldoc.org doesn't extend over the contrib modules as well. Gordon Anisa wrote:
There is a place now in the new handbook for contributed module information. :)
To contribute, use the docs list.
Anisa.
Gordon Heydon wrote:
Hello,
I had a fun morning. When I got up this morning I had an email from a client with a problem with the ecommerce module which was not sending out the email alerts to customers. In the end it turned out to be a problem with the payment gateway that I had developed for him. So here I am investigating/programming and fixing his problem before I could leave to go to another client, so doing some creative thinking and find the solution as fast as possible.
This got me to thinking, and the main reason that this problem occured in the first place. Basically the problem was that "Documentation for contributed modules sux" (I am not singling out the ecommerce module, AFAIK it all sux).
Basically I feel the problem is that there is no place for development/user/admin documention on drupal.org/drupaldoc.org for any of the docuementation that relates to the contributed modules. If there was something like this then the fact that the payment gateway module is required to call the functions to send the emails and may not have been making up a solution to a problem that I didn't know about on the fly.
For a start I think that it would be good to have drupaldoc.org include all the documentation from the contributed modules. I know that a lot do not have the the phpdoc comments (I know that mine do not, but I would fix this if it is going to be used).
Then maybe adding sections to the user and admin sections of the handbook so that the contributed modules can build documentation. This also means that people who cannot program or contrbute modules can contribute by writing documentation much like we do now for the core documentation.
Just my thoughts. Gordon.
!DSPAM:4284346d95454551116848!
Just attempted to install taxonomy access module. Couldn't agree more. -----Original Message----- From: drupal-devel-bounces@drupal.org [mailto:drupal-devel-bounces@drupal.org] On Behalf Of Gordon Heydon Sent: Friday, May 13, 2005 12:05 AM To: drupal-devel@drupal.org Subject: Re: [drupal-devel] A little about my morning. - Ranton Documentation Hello, Thanks for the pointer, but being a developer the biggest beef I have is the fact the the drupaldoc.org doesn't extend over the contrib modules as well. Gordon Anisa wrote:
There is a place now in the new handbook for contributed module information. :)
To contribute, use the docs list.
Anisa.
Gordon Heydon wrote:
Hello,
I had a fun morning. When I got up this morning I had an email from a client with a problem with the ecommerce module which was not sending out the email alerts to customers. In the end it turned out to be a problem with the payment gateway that I had developed for him. So here I am investigating/programming and fixing his problem before I could leave to go to another client, so doing some creative thinking and find the solution as fast as possible.
This got me to thinking, and the main reason that this problem occured in the first place. Basically the problem was that "Documentation for contributed modules sux" (I am not singling out the ecommerce module, AFAIK it all sux).
Basically I feel the problem is that there is no place for development/user/admin documention on drupal.org/drupaldoc.org for any of the docuementation that relates to the contributed modules. If there was something like this then the fact that the payment gateway module is required to call the functions to send the emails and may not have been making up a solution to a problem that I didn't know about on the fly.
For a start I think that it would be good to have drupaldoc.org include all the documentation from the contributed modules. I know that a lot do not have the the phpdoc comments (I know that mine do not, but I would fix this if it is going to be used).
Then maybe adding sections to the user and admin sections of the handbook so that the contributed modules can build documentation. This also means that people who cannot program or contrbute modules can contribute by writing documentation much like we do now for the core documentation.
Just my thoughts. Gordon.
!DSPAM:4284346d95454551116848!
+1 from me on having contributed modules phpdoc'd on drupaldoc.org also. If it's good to have phpdocs for core modules, then the same benefits accrue from having the same for contributed modules. One thing that concerns me is how documentation is currently spread out over several different sources. It would be nice to pull everything together on one site. If properly designed, such a site could serve the needs of all documentation users - administrators, developers, users, ... Was there not a suggestion to establish docs.drupal.org for this purpose? Djun On 12 May 2005, at 10:13 PM, Kent Livingston wrote:
Just attempted to install taxonomy access module.
Couldn't agree more.
-----Original Message----- From: drupal-devel-bounces@drupal.org [mailto:drupal-devel-bounces@drupal.org] On Behalf Of Gordon Heydon Sent: Friday, May 13, 2005 12:05 AM To: drupal-devel@drupal.org Subject: Re: [drupal-devel] A little about my morning. - Ranton Documentation
Hello,
Thanks for the pointer, but being a developer the biggest beef I have is the fact the the drupaldoc.org doesn't extend over the contrib modules as well.
Gordon
Hi, There /must/ have been some good reason for not including the contribs in the docs. Anyone? However, I cant agree more: we need contribs in drupaldocs as well. Only then can we start ranting and screaming at contrib authors that did not provide proper docs. We can do that now, but its kinda unfair, since there is no real place to do so. Also: I think we must really draw a very clear line between user documentation and developer documentation. Historically these two groups where the same persons in the Drupal comm. But AFAIK this has changed: thus developers and users are two separate gruops now. Users should never have to see information about the theme system etc, while developers should be easily able to avoid docs about what taxonomy is. I am not saying that this is not the case atm, just that it still is a little unclear here and there. Allthough it already has impressively improved lately! Bryghts documentation is a very good example of the user docs IMO. Ber Op vrijdag 13 mei 2005 07:49, schreef puregin:
+1 from me on having contributed modules phpdoc'd on drupaldoc.org also. If it's good to have phpdocs for core modules, then the same benefits accrue from having the same for contributed modules.
One thing that concerns me is how documentation is currently spread out over several different sources. It would be nice to pull everything together on one site. If properly designed, such a site could serve the needs of all documentation users - administrators, developers, users, ...
Was there not a suggestion to establish docs.drupal.org for this purpose?
Djun
On 12 May 2005, at 10:13 PM, Kent Livingston wrote:
Just attempted to install taxonomy access module.
Couldn't agree more.
-----Original Message----- From: drupal-devel-bounces@drupal.org [mailto:drupal-devel-bounces@drupal.org] On Behalf Of Gordon Heydon Sent: Friday, May 13, 2005 12:05 AM To: drupal-devel@drupal.org Subject: Re: [drupal-devel] A little about my morning. - Ranton Documentation
Hello,
Thanks for the pointer, but being a developer the biggest beef I have is the fact the the drupaldoc.org doesn't extend over the contrib modules as well.
Gordon Regards, Bèr -- [ Bèr Kessels | Drupal services www.webschuur.com ]
On Fri, 2005-05-13 at 09:58 +0200, Gerhard Killesreiter wrote:
On Fri, 13 May 2005, Bèr Kessels wrote:
There /must/ have been some good reason for not including the contribs in the docs. Anyone?
Most contrib modules used to not contain any phpdoc comments.
Yes this is known, but at this stage even if you put this information in your contrib modules it is not being used. So why go to the trouble. I know that it is a little bit of a egg and chicken thing, but it the information is being loaded into drupaldoc.org then more developers would be more inclined to include the information. Gordon.
Is there any documentation of the PHPDoc tags? The documentation http://www.phpdoc.de/doc/index.html ...is non-existent and I am not inclined to read javadoc documentation. Some documentation and a clear minimum standard for inclusion in the official docs would go a long way toward inspiring folks to write that documentation. On 5/14/05, Gordon Heydon <gordon@heydon.com.au> wrote:
On Fri, 2005-05-13 at 09:58 +0200, Gerhard Killesreiter wrote:
On Fri, 13 May 2005, Bèr Kessels wrote:
There /must/ have been some good reason for not including the contribs in the docs. Anyone?
Most contrib modules used to not contain any phpdoc comments.
Yes this is known, but at this stage even if you put this information in your contrib modules it is not being used. So why go to the trouble.
I know that it is a little bit of a egg and chicken thing, but it the information is being loaded into drupaldoc.org then more developers would be more inclined to include the information.
Gordon.
On Sat, 14 May 2005, Gordon Heydon wrote:
On Fri, 2005-05-13 at 09:58 +0200, Gerhard Killesreiter wrote:
On Fri, 13 May 2005, Bèr Kessels wrote:
There /must/ have been some good reason for not including the contribs in the docs. Anyone?
Most contrib modules used to not contain any phpdoc comments.
Yes this is known, but at this stage even if you put this information in your contrib modules it is not being used. So why go to the trouble.
I know that it is a little bit of a egg and chicken thing, but it the information is being loaded into drupaldoc.org then more developers would be more inclined to include the information.
I see your point. There are two things to do: Verify that none of the contrib modules break the output of api.module in any way and after that talk to JonBob and Kjartan about integrating contribs to drupaldocs. I am willing to do part two. ;) Cheers, Gerhard
On Fri, 13 May 2005 07:04:42 +0200, Gordon Heydon <gordon@heydon.com.au> wrote:
Hello,
Thanks for the pointer, but being a developer the biggest beef I have is the fact the the drupaldoc.org doesn't extend over the contrib modules as well.
I'd appreciate it if drupaldocs.org worked for contrib modules as well. -- Tim Altman
On May 12, 2005, at 8:04 PM, Gordon Heydon wrote:
Hello,
I had a fun morning. When I got up this morning I had an email from a client with a problem with the ecommerce module which was not sending out the email alerts to customers. In the end it turned out to be a problem with the payment gateway that I had developed for him. So here I am investigating/programming and fixing his problem before I could leave to go to another client, so doing some creative thinking and find the solution as fast as possible.
This got me to thinking, and the main reason that this problem occured in the first place. Basically the problem was that "Documentation for contributed modules sux" (I am not singling out the ecommerce module, AFAIK it all sux).
Great observation. Here are some suggestions. First, there are over 1300 messages in the Drupal docs thread, so if you really want to make stuff happen with respect to documentation that's the place to do it. Second, if you are serious then you are going to need a methodology and examples for getting that developer documentation written. Take a look at this: http://dev.bryght.com/t/wiki/ DrupalDocumentationProcess as an example what many members of the docs team are considering as a baseline before contributing to actual documentation. Third, if you do decide to do this then there's a lot of work and grunt research that you want to do to make your volunteers effective. Take a look at these tables I put together for the documentation sprint I ran last week. This is Drupal core: http://dev.bryght.com/t/wiki/ DrupalAdminHelpDocumentation This is the 29 contrib modules that ship with CivicSpace: http:// dev.bryght.com/t/wiki/DrupalContribsAdminHelpDocumentation You are also going to want a test site set up running Drupal Head for your volunteers. They are going to be able to use the application as they documenting the code to confirm it does what the doc comments say it does. I am pretty focused on admin help right now but I can advise on a Drupaldocs sprint if you want. Cheers, Kieran
participants (9)
-
Anisa -
Bèr Kessels -
Earl Dunovant -
Gerhard Killesreiter -
Gordon Heydon -
Kent Livingston -
Kieran Lal -
puregin -
Tim Altman