Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.
By delay on
One thing I love about the PHP help at php.net and I find incredibly useful is the user submitted comments.
For example: http://us2.php.net/manual/en/function.preg-match.php
It really seems to let the community flesh out the documentation with real world examples and things that have been learned and used with a particular function or example. Are there any plans for drupal to do this? I know with the drupal backend this would be trivial to implement from a technical standpoint though their may need to be assigned moderators to approve submissions for a function or topic in the documentation.
I think this would make an excellent addition and it would be a lot easier than trying to scavenge the forums for similar information.
I am new to drupal so I didn't know if this had been discussed before. I didn't see it in a quick search of the forums.
Comments
Here is an example as to
Here is an example as to where I would like to see users be able to add comments to documentation.
http://api.drupal.org/api/HEAD/function/hook_load
great idea
It's a great idea. I always wanted to add useful comments to the API's documentation.
I don't think so. The API pages are not nodes, so there's nothing to attach the comments to.
Well that definitely makes
Well that definitely makes it much harder to implement.
I still think it would be worth doing even if you had to either convert the api docs into nodes or write something custom that allows comments to be attached.
Support requests
I'm afraid most comments will be support requests, as it often with the case with handbooks on drupal.org. We'd certainly need a handful of moderators to prevent the occasional gem from being buried in rubbish.
--
The Manual | Troubleshooting FAQ | Tips for posting | Make Backups! | Consider creating a Test site.
Possibly doing it without moderators.
Yes I believe php uses moderators. However I was thinking a little bit on how to do it without moderators. Use a system similar to digg.com commenting system where users vote relevant comments up or down. You would have two tabs. Approved and unapproved comments. Approved would show in the default docs and you could see all unapproved comments in the secondary tab. So if you don't see what you need in the approved tab you then go through the unapproved tab and see if there was anything useful. A user could then give it a + vote if they found a good comment. Once a threshold of votes is passed the comment becomes an approved comment.
Also support requests in the comments could become unweildy, but they may be quite useful. If ten people ask the same question on some implementation of hook_load and one person answers it. The chance of this getting asked again is much less and you have less support requests coming into the forums about this. Also if it does become unweildy and good info is not being collected it isn't that hard to just shut comments off.
...
I don't think so. The API is browsed by programmers, not by common users.
I agree with amnon.
People who are reading the API documentation are people who already know the basics and just need to quickly look up functions.
There are a few times I have noticed something in the api docs that could be improved upon, but due to not being able to comment on it, moved on to something else and forgot about it.
Most of the users I know are afraid of the words "read the API documentation," and would never voluntarily browse them. ;)
Hmm
Well I'm afraid not, but we will only see when we try.
BTW: To improve most of the api documentation, modify the phpdoc comment on top of the function (yes in core code), create a patch and post it to the issues queue. The api docs are automatically generated from those comments.
--
The Manual | Troubleshooting FAQ | Tips for posting | Make Backups! | Consider creating a Test site.