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 <[email protected]> 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