(Unmoderated) manual notes are bad, mmkay?
I’ve had a couple of whinges on IRC lately about why I’m not thrilled with having user notes in their current form in the PHP manual; we get entirely too many questions in ##php from people who’ve copied code out of a note and are then annoyed when it turns out the code is wrong, broken, horrible, or all of the above.
I present this example from the DateTime::getTimestamp() manual page. It’ll be disappearing from the mirrors over the next few hours, because I’ve deleted it (and posted a much simpler note in its place), so here was its content, for posterity:
If you are using PHP < 5.3.0 you can use this function instead:
<?php function DateTime_getTimestamp(&$dt) { $dtz_original = $dt -> getTimezone(); $dtz_utc = new DateTimeZone("UTC"); $dt -> setTimezone($dtz_utc); $year = intval($dt -> format("Y")); $month = intval($dt -> format("n")); $day = intval($dt -> format("j")); $hour = intval($dt -> format("G")); $minute = intval($dt -> format("i")); $second = intval($dt -> format("s")); $dt -> setTimezone($dtz_original); return gmmktime($hour,$minute,$second,$month,$day,$year); } ?>
It’s fair to say that’s an interesting approach. The normal way of doing it would be:
<?php $timestamp = $dt->format('U'); ?>
I don’t know what the answer is — moderation has its own problems to do with workload, as PEAR can attest — but a system that’s letting that go up as recommended practice (and stay up for a month) has to be looked at.
October 30th, 2009 at 17:03
Wouldn’t it be better to be able to reply to the comment, teaching the poster (and readers) that there’s a better way? Seems more effective than deleting it.
October 30th, 2009 at 19:40
Of all the technologies I’ve used I have found PHP to have the best documentation, this is in no small part down to the user comments.
Sure – they are of variable quality and have to be read carefully (and with a pinch of salt)
But many times I’ve found clarifications of syntax in user comments that have helped me.
- and I have the impression that useful comments get incorporated into the documentation.
Maybe a more prominent health warning would be useful to warn unwary users that comments are not checked.
Sure
October 30th, 2009 at 19:57
Maybe the documentation pages could get a wiki part that is example-focused and help-focused instead or in addition to the comments? Because there are always undocumented tricks and examples in the comments that could be collected in a wiki-like subsystem. The only difference would be that you don’t post you experience in the form of a comment but as a chapter in a commonly editable help section near the pure documentation part. And others could correct your thoughts and pick most interesting facts – because I love reading through the comments, there’s good examples but as you said – quality varies. Plus sometimes I am just not really interested in the story behind a certain piece of code.
October 30th, 2009 at 21:58
When I and a few other programmers I know first started to use PHP, the main attraction was the documentation. Not because of the actual documentation but because of the user comments. As Sean pointed out, the nuggets of clarification and ‘better’ examples made flipping through them better. I’ve also found out about certain PHP functions because of Google searches that hit keywords in the comments section.
Ivo: the problem isn’t that there’s no one correcting someone’s improper code, but that the comments in the document page are presented linearly. They need to be threaded for that to be visable. There are a few times I’ve scrolled up and down trying to figure out who’s correcting who and which is correct. =/
Bernhard brings up a good point about more of a wiki-style documentation. It would be hot if they did something along those lines.
October 30th, 2009 at 23:15
what about the ability to rate comments? if a comment reaches a certain negative threshold, it gets hidden. maybe also give the ability to put a comment on your rating that gets attached to the original comment, so that people can see WHY it’s being rated down as well.
October 31st, 2009 at 01:01
[...] this new post to his blog Adam Harvey shares his opinion on unmoderated notes dropped directly into the PHP [...]
October 31st, 2009 at 03:59
Think it would have made sense to leave it there and show the much better way of doing it.
See it as a wrong way right way of doing things. People can learn from that.
Would be nice if we had something like Stackoverflow for the php manual.
October 31st, 2009 at 05:31
@James Dempster: agreed. Or allow users with high StackOverflow reps for PHP be able to make manual edits (w/ some sort of approval process).
October 31st, 2009 at 09:08
In theory, user comments exist to be integrated into the PHP manual sources. So in this case, someone might see it and realize the page itself could use an example and write one. If the user supplied example is good, use it (and credit them accordingly). Of course, theory does not always turn into practice.
The user comments were cutting edge 10 years ago, and directly contributed to the success of PHP. Design a new system? Sounds like a great idea! Please email phpdoc@lists.php.net with thoughts (and check the archives for others).
Adam, I think you should write patches and ask for karma to the PHP manual sources. ;)
October 31st, 2009 at 12:55
Granted, the User-Contributed Notes can be quite spotty sometimes.
But they are often the BEST part of the documentation, imho, as they provide the examples, discussion, and real-world issues that are so often lacking.
They are also absolutely crucial in that nascent period when new functions appear but no PHP Devs bothered to document them yet.
It would not be that much effort for the Devs to prune them a bit more often.
October 31st, 2009 at 16:04
+1 on the idea of Robert to create a self-moderating system by adding rating options. Since most of the time you only read the comments when you have a problem, you know exactly which comment helped you out the best at the end. Kind of an Experts Exchange “accepted solution” deal. Together with a default sorting by rating, and the possibility to comment on notes (something that is already happening but in a long-winded way of adding new notes), I think we’ll have a real good system that makes great use of the massive userbase PHP has.
I don’t think a wiki or any other external project is the solution btw, the notes and manual should stay in the same place to work IMO.
November 1st, 2009 at 00:10
Btw, for those curious about how much note editing/deleting has gone on over the years:
- http://doc.php.net/php/notes_stats.php
April 28th, 2010 at 19:24
Hi Adam,
Just a remark and a question:
Why is the object passed by reference in function DateTime_getTimestamp(&$dt) ??
PHP5 objects are no more copies. So I think passing the object $dt by reference is redundant or no more makes sense?
Would like to hear your comment on this one.
Thanks,
K. Wasseem
April 28th, 2010 at 22:33
@K. Wasseem
I have absolutely no idea. That was the original note, not the one I wrote in its place. My guess is that you’re right, and that it’s a remnant from what the original author heard about how objects were passed in PHP 4.
April 28th, 2010 at 23:30
Adam,
thanks for the reply ;)
Yes perhaps it’s a remnant of php4
Keep posting,
K. Wasseem
(7php.com)
June 8th, 2010 at 17:59
There’s no problem with unmoderated blogs. It gives others the chance to comment.