On Wed, Jan 9, 2013 at 1:05 PM, Levi Morrison <morrison.l...@gmail.com>wrote:
> Firstly, I apologize if this is the incorrect list. > > I'm trying to clean up the user notes in certain portions of the > manual. As such, I've reviewed a lot of user contributed notes and > found a few common types of notes that bother me: > > 1. Code snippets to do something similar to the current function. > I've taken a stance on this. If the note provides a way to solve a problem not otherwise easily solved by that function then I believe we should allow it. Examples of this are user land functions that implement the same functionality for older versions of PHP (although if it's something like "how to do this in PHP 4" I think we can make an exception). This might also include functions from PECL extensions that can easily be implemented in user land (again we might not want 400 SLOC examples in user notes, if it's short and sweet I'm fairly tolerant of it and as long as the code doesn't present any overly faulty logic -- like it just doesn't do what the author says it will do or it's a security risk). Another way to look at this is if the function lacks something not otherwise covered by another function. To elaborate I've seen user implementations of count that work on multidimensional arrays. Obviously PHP has no similar function. There is no count_recursive in PHP so I think that's fine and it's fairly simple to implement in user land. Users trying to help other users solve common problems we haven't easily solved for them should be tolerated in the manual, in my opinion. Again using common sense when making this judgement is required. We don't need 500 implementations that do the same thing. I usually just leave the first note that provided the implementation or now you can even chose to leave the top rated note if you'd like. If the function has a minor typo or mistake simply consider correcting it instead of deleting it. > 2. Reports of performance compared to function X. Incorrect > testing methods are usually involved. > Bench marking is rampant in PHP and I don't think it adds any value to the manual, personally. Knowing that function X tested faster than function Y by 9.348 milliseconds on Windows vs. Linux vs. Mac vs. VoodoOS is not really helpful to me. I don't know about everyone else, but I really don't think those kinds of notes belong in the manual at all. People may feel free to bench mark things on their own time, but we aren't documenting anything worthy in the manual with that. > 3. Reports an edge-case not included in the manual section. > I'm perfectly fine with that type of thing. Edge cases in PHP are not scarce. They're actually more common than we care to admit. People are doing all kinds of interesting things with PHP these days. I'm happy to see people spot edge cases as long as they are presenting some kind of a solution for their reported edge case and not just informing people that edge cases exist. Obviously edge cases exist in every language. No need to clutter the manual pages with edge cases. We'd have a lot more than ~27,000 notes in the manual if we let that go. Again common sense is always cautioned when making these decisions. It's a judgement call, but I like to consider the likely-hood of the use case as well as the applicability of the solution. If there is no solution offered it's rare that just stating an edge case will benefit anyone. > > Some pages of the manual have severe problems with #1. See > http://php.net/manual/en/function.count.php for an example one such > page. A blanket policy of deleting notes like this would probably be > harmful, but on this page in particular I feel like deleting all > comments of this type. > Yup, I've found pages with over 100 notes (believe it or not). This is nothing new and as Adam points out I often see him, Dan Brown and myself deleting dozens of notes from a particular page at a time. Just skimming over them you can tell if there is a lot of repeated information. This is one that really annoys me when you have 20 people all saying the same thing. Or when you have 20 people all trying to correct each others code and it turns into a 4chan thread. I delete those all the time. One thing to note now (no pun intended) is that we have user voting in place. We have a lot more eyes on user notes than we did before. Users are making their own judgement calls and that should help us eliminate bad notes more easily. If you are finding a lot notes on the page you are likely to find a lot of notes that have also been down voted to the bottom of the page. My suggestion is that you simply scroll down to the bottom of such pages and see if any of those negative rated notes aren't worth keeping around. Perhaps their information is too outdated (we do have a lot of notes in the manual that are now over a decade old). Perhaps the note has horrible grammar/spelling (doesn't make sense) or bad code that just doesn't work. Perhaps the note is just stating a moot point. Just by looking at http://php.net/count I can tell you there are at least 5 notes (at the time of this writing) that currently have a rating of below 50% at the bottom of that page. Those are notes we can delete since they have such bad ratings and just skimming over them you can tell they are just repeating each other. You can tell the notes on this page aren't strongly favored just by the fact that the top rated note there is currently at a 66% rating. > > What really bothers me about #2 is that the testing methods are > usually skewing the results. I don't feel like editing is appropriate > in these situations but am unsure if deletion is appropriate either. > > In the case of #3 I feel like we should simply update the manual. The > question then becomes: should we keep the comment? > > As far as updating the manual we have to be careful. Not all edge cases can be covered by the manual but obviously we already make notes and warnings for certain common edge cases. For example, I added this caution to the manual for http://php.net/usort "Returning non-integer values from the comparison function, such as float, will result in an internal cast to integer of the callback's return value. So values such as 0.99 and 0.1 will both be cast to an integer value of 0, which will compare such values as equal." After a user pointed out that they were trying to something like usort($array, function ($a, $b) { return $b - $a; }); with an array that contained floats and wondering why their array wasn't being sorted properly. Clearly we document that the function expects the callback to return "an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second.". Where integer is as plain as day there, but they still felt the manual was not clear enough and that this was an edge case. So I added the caution there anyway. I guess it benefits people. I honestly can't be too sure. So again make your own judgement calls there. I try to be fair to everyone involved and do what's best for our users. > --- > > Related: is there a posted guideline for moderating user contributed notes? > > -- > PHP Webmaster List Mailing List (http://www.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > >
