Re: Notes Status, 24899 total

On Sat, Aug 15, 2020, at 2:10 PM, Ben Ramsey wrote: > > On Aug 15, 2020, at 13:43, Rowan Tommins <rowan.collins@gmail.com> wrote: > > Rather than getting rid of notes, I think we should look at how to improve that process. > > For instance, as we move towards git for the manual itself, we could have a system where a PR could > > list the notes that it makes redundant, and automatically delete them once approved. Then we could > > embrace edit suggestions as comments (rather than directing people to the bug tracker), and > > encourage people to raise a PR incorporating those suggestions. > > > I think you’re right. User notes aren’t intended as a place to ask > questions and get answers. They are intended to supplement the examples > in the manual, and many of them are valuable for this reason. Perhaps > when we make it easier to contribute to the manual (through Git, etc.), > more users will be able to provide updates to the manual instead of > adding user notes. > > Cheers, > Ben Oh boy, I poked the nest it seems... :-) I think there is value to a two layer approach: The doc page itself, with very curated examples and descriptions, and semi-curated bonus examples. For instance, looking at array_map(): https://www.php.net/manual/en/function.array-map.php#102130 - This comment is mostly useless. It's just repeating something already described. It can be deleted outright. https://www.php.net/manual/en/function.array-map.php#96564 - This comment suggests we need one more example inline in the page, or a mention, or something about anonymous functions being a-ok. Then we can delete the comment. https://www.php.net/manual/en/function.array-map.php#80571 - This is an array_map-ish alternate function for those who want similar but not quite the same behavior. I would not want to put that into the page directly, but it potentially has value in a second-tier role, right where it is, assuming such comments are periodically checked to remove any that are just plain wrong or long since no longer applicable. So, I agree we should have some clearer policy around how to go about each of those other than me asking "hey, can I delete these?" (Apparently I do now have access to delete comments, which is only slightly horrifying... Whee!) I'm flexible on what that is; I just want to avoid deleting things too aggressively and getting yelled at. --Larry Garfield