Negatively Voted Notes

Mailing Lists php.doc
1

Hi!

There are currently nearly 20000 notes in the documentation, with many
having a very high negative rating.

For example, there are:

1131 notes older than a year, with a rating less than -10
2339 notes older than a year, with a rating less than -5
5761 notes older than a year, with a rating less than -1

The worst offender is:

PHP: Cookies - Manual with -159 (not sure why the website says -153)
PHP: Attributes overview - Manual with -104

We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a
  year.
- come up with a plan to crowd source going through the other thousands
  of notes to see if they need to be deleted or integrated into the
  actual text. Each documentation page now has a link to the XML source
  (such as doc-en/language/attributes.xml at master · php/doc-en · GitHub)

Comments?

cheers,
Derick

--
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: Xdebug: Support

mastodon: @derickr@phpc.social @xdebug@phpc.social

2

+1 vote for deleting all votes with a lower rating than -5 and more than a year old.

I’m happy to dedicate some time to trawling through the remaining comments and deleting the worst offenders manually. I already have comment-admin karma

···

Mike Griffiths
mgriffiths@gmail.com

3

I think this is a great initiative. +1 to deleting all notes with less than -5 rating and older than a year.

On Wed, Jul 10, 2024, at 10:28 AM, Mike Griffiths wrote:

+1 vote for deleting all votes with a lower rating than -5 and more
than a year old.

I'm happy to dedicate some time to trawling through the remaining
comments and deleting the worst offenders manually. I already have
comment-admin karma

On Wed, 10 Jul 2024 at 15:20, Derick Rethans <derick@php.net> wrote:

Hi!

There are currently nearly 20000 notes in the documentation, with many
having a very high negative rating.

For example, there are:

1131 notes older than a year, with a rating less than -10
2339 notes older than a year, with a rating less than -5
5761 notes older than a year, with a rating less than -1

The worst offender is:

PHP: Cookies - Manual with -159 (not sure why the website says -153)
PHP: Attributes overview - Manual with -104

We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a
  year.
- come up with a plan to crowd source going through the other thousands
  of notes to see if they need to be deleted or integrated into the
  actual text. Each documentation page now has a link to the XML source
  (such as doc-en/language/attributes.xml at master · php/doc-en · GitHub)

Comments?

cheers,
Derick

--
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: Xdebug: Support

mastodon: @derickr@phpc.social @xdebug@phpc.social

--

Mike Griffiths
mgriffiths@gmail.com

4

Maybe older than 5 is better? The interpreter is not written from scratch every year (and even 5).

ср, 10 лип. 2024 р., 17:43 користувач Klaus Silveira <contato@klaussilveira.com> пише:

I think this is a great initiative. +1 to deleting all notes with less than -5 rating and older than a year.

On Wed, Jul 10, 2024, at 10:28 AM, Mike Griffiths wrote:

+1 vote for deleting all votes with a lower rating than -5 and more
than a year old.

I’m happy to dedicate some time to trawling through the remaining
comments and deleting the worst offenders manually. I already have
comment-admin karma

On Wed, 10 Jul 2024 at 15:20, Derick Rethans <derick@php.net> wrote:

Hi!

There are currently nearly 20000 notes in the documentation, with many
having a very high negative rating.

For example, there are:

1131 notes older than a year, with a rating less than -10
2339 notes older than a year, with a rating less than -5
5761 notes older than a year, with a rating less than -1

The worst offender is:

https://www.php.net/manual/en/features.cookies.php#128286 with -159 (not sure why the website says -153)
https://www.php.net/manual/en/language.attributes.overview.php#126887 with -104

We discussed this during one of our foundation meetings, and we propose:

  • to delete all notes with a rating less than -5 that are older than a
    year.
  • come up with a plan to crowd source going through the other thousands
    of notes to see if they need to be deleted or integrated into the
    actual text. Each documentation page now has a link to the XML source
    (such as https://github.com/php/doc-en/blob/master/language/attributes.xml)

Comments?

cheers,
Derick

–
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: https://xdebug.org/support

mastodon: @derickr@phpc.social @xdebug@phpc.social

–

Mike Griffiths
mgriffiths@gmail.com

5

On Wednesday, 10 July 2024 at 15:18, Derick Rethans <derick@php.net> wrote:

Hi!

There are currently nearly 20000 notes in the documentation, with many
having a very high negative rating.

For example, there are:

1131 notes older than a year, with a rating less than -10
2339 notes older than a year, with a rating less than -5
5761 notes older than a year, with a rating less than -1

The worst offender is:

PHP: Cookies - Manual with -159 (not sure why the website says -153)
PHP: Attributes overview - Manual with -104

We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a
year.
- come up with a plan to crowd source going through the other thousands
of notes to see if they need to be deleted or integrated into the
actual text. Each documentation page now has a link to the XML source
(such as doc-en/language/attributes.xml at master · php/doc-en · GitHub)

Comments?

As one of the primary persons that tries to triage new notes, I am strongly in favour.
Unrelated, it would be very nice if we could improve the spam filters for user notes somewhat, but this is unrelated to removing unpopular votes.

One question, should this possibly become a monthly cron job that checks for the user notes and removes those that fall below the above criterias?

Best regards,

Gina P. Banyard

6

In a prior life I used to take an hour a week looking at “best notes” and the “bottom rated notes” on master and integrate/delete them:

https://main.php.net/manage/user-notes.php?view=notes&type=3
https://main.php.net/manage/user-notes.php?view=notes&type=4

Maybe we could make the “best notes” list publicly available with the goal of soliciting old/existing/new doc writers getting their feet wet by inlining good notes?

I think it makes sense to automatically delete notes that have been downvoted for a while, and I think the proposed threshold makes sense.

-Hannes

On Wed, Jul 10, 2024 at 7:18 AM Derick Rethans <derick@php.net> wrote:

Hi!

There are currently nearly 20000 notes in the documentation, with many
having a very high negative rating.

For example, there are:

1131 notes older than a year, with a rating less than -10
2339 notes older than a year, with a rating less than -5
5761 notes older than a year, with a rating less than -1

The worst offender is:

https://www.php.net/manual/en/features.cookies.php#128286 with -159 (not sure why the website says -153)
https://www.php.net/manual/en/language.attributes.overview.php#126887 with -104

We discussed this during one of our foundation meetings, and we propose:

  • to delete all notes with a rating less than -5 that are older than a
    year.
  • come up with a plan to crowd source going through the other thousands
    of notes to see if they need to be deleted or integrated into the
    actual text. Each documentation page now has a link to the XML source
    (such as https://github.com/php/doc-en/blob/master/language/attributes.xml)

Comments?

cheers,
Derick

–
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: https://xdebug.org/support

mastodon: @derickr@phpc.social @xdebug@phpc.social

7

On Wed, 10 Jul 2024 at 15:18, Derick Rethans <derick@php.net> wrote:

Hi!

There are currently nearly 20000 notes in the documentation, with many
having a very high negative rating.

For example, there are:

1131 notes older than a year, with a rating less than -10
2339 notes older than a year, with a rating less than -5
5761 notes older than a year, with a rating less than -1

The worst offender is:

https://www.php.net/manual/en/features.cookies.php#128286 with -159 (not sure why the website says -153)
https://www.php.net/manual/en/language.attributes.overview.php#126887 with -104

We discussed this during one of our foundation meetings, and we propose:

  • to delete all notes with a rating less than -5 that are older than a
    year.
  • come up with a plan to crowd source going through the other thousands
    of notes to see if they need to be deleted or integrated into the
    actual text. Each documentation page now has a link to the XML source
    (such as https://github.com/php/doc-en/blob/master/language/attributes.xml)

Comments?

cheers,
Derick

–
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: https://xdebug.org/support

mastodon: @derickr@phpc.social @xdebug@phpc.social

This is something im both For and Against.

On the for side, alot of these notes are negative rated for a reason, bad code, bad advice, incorrect usage, etc etc

But on the against said is removing information, no matter how bad the code is or misunderstood, in my eyes no information should be removed. Let users see others’ mistakes, so they dont repeat them.
This is what the rating system is for. The only stuff that I wouldn’t be against is clearly
advertising/promotional/spam posts.

If we had a thread system for these comments, so others can reply, they can point out mistakes/bad code/incorrect usage and those reading can learn what and what not to do.

8

On 10 July 2024 18:47:07 BST, fennic log <fenniclog@gmail.com> wrote:

On Wed, 10 Jul 2024 at 15:18, Derick Rethans <derick@php.net> wrote:

Hi!

There are currently nearly 20000 notes in the documentation, with many
having a very high negative rating.

For example, there are:

1131 notes older than a year, with a rating less than -10
2339 notes older than a year, with a rating less than -5
5761 notes older than a year, with a rating less than -1

The worst offender is:

PHP: Cookies - Manual with -159 (not
sure why the website says -153)
PHP: Attributes overview - Manual
with -104

We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a
  year.
- come up with a plan to crowd source going through the other thousands
  of notes to see if they need to be deleted or integrated into the
  actual text. Each documentation page now has a link to the XML source
  (such as
doc-en/language/attributes.xml at master · php/doc-en · GitHub)

Comments?

This is something im both For and Against.

On the *for* side, alot of these notes are negative rated for a reason, bad
code, bad advice, incorrect usage, etc etc

But on the *against* said is removing information, no matter how bad the
code is or misunderstood, in my eyes no information should be removed. Let
users see others' mistakes, so they dont repeat them.
This is what the rating system is for. The only stuff that I wouldn't be
against is clearly
advertising/promotional/spam posts.

If we had a thread system for these comments, so others can reply, they can
point out mistakes/bad code/incorrect usage and those reading can learn
what and what not to do.

Notes where never meant to be helpful to other developers. They were hints to the editors to include missing information, to add clarification, and sometimes to add new examples *into* the documentation, and then delete the note. This is less needed now as each page has a direct link to "report a bug" or the XML source.

The rating systems was another hint to the editors of the manual to see how wrong of helpful a hint for them was.

Walls of code with "special functions", or questions, or incorrect comments were always deleted without prejudice.

Help threads and discussions belong on the php-general list of somewhere else.

cheers
Derick

9

On 10/07/2024 19:42, Derick Rethans wrote:

Notes where never meant to be helpful to other developers. They were hints to the editors

If that's the case, why would they even be public?

Cheers,
Bilge

10

On Wed, Jul 10, 2024, at 7:18 AM, Derick Rethans wrote:

We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a
  year.
- come up with a plan to crowd source going through the other thousands
  of notes to see if they need to be deleted or integrated into the
  actual text. Each documentation page now has a link to the XML source
  (such as doc-en/language/attributes.xml at master · php/doc-en · GitHub)

Comments?

Yes, please.

The original intent for the notes system was to allow low-effort contributions from people who would otherwise not learn how to edit DocBook to make contributions (and in an era where you couldn't just do easy pull requests on GitHub, but had to send patches to a list or send smoke signals or something – it was a long time ago).

Notes were never meant to be precious or long-lived, and I don't see any problem with leveraging the voting feature to automatically cull notes that have been voted down. Waiting a whole year to eliminate notes with a large negative rating is probably longer than necessary.

Jim

11

Hi

On 7/10/24 16:18, Derick Rethans wrote:

Comments?

For now I'm only asking to give me the time to go through the ext/random stuff myself before the automated deletion is performed (i.e. defer this until after feature freeze at least).

Similarly to what Fennic Log replied, for ext/random I can see how some of the bad comments could serve as good data for new warnings to add to the documentation. Randomness is pretty unintuitive and it's easy to make conceptual mistakes that other folks made before.

Best regards
Tim Düsterhus

12

On 10.07.2024 at 21:24, Bilge wrote:

On 10/07/2024 19:42, Derick Rethans wrote:

Notes where never meant to be helpful to other developers. They were
hints to the editors

If that's the case, why would they even be public?

Actually, there are guidelines regarding the handling of user notes[1]
(I'd linked to doc.php.net, but that server is currently down).
According to these guidelines only few notes should be left (at least
regarding the notes that have been submitted in the last months, if not
years).

So while I do not agree that these notes where *never* meant to be
helpful to other developers, I would suggest to shut down that
possibility – like others have already said, there are better ways to
provide such information nowadays.

[1] <https://github.com/php/web-doc/blob/master/tutorial/user-notes.md&gt;

Cheers,
Christoph

13

Indeed, as Derick mentioned, the notes were meant to know that something is missing or wrong in the manual, not as a forum for discussion.

/me goes back to his antediluvian cave :slight_smile:

On 2024-07-10 13.42 -05 Derick Rethans <derick@php.net> wrote:

On 10 July 2024 18:47:07 BST, fennic log <fenniclog@gmail.com> wrote:
>On Wed, 10 Jul 2024 at 15:18, Derick Rethans <derick@php.net> wrote:
>
>> Hi!
>>
>> There are currently nearly 20000 notes in the documentation, with many
>> having a very high negative rating.
>>
>> For example, there are:
>>
>> 1131 notes older than a year, with a rating less than -10
>> 2339 notes older than a year, with a rating less than -5
>> 5761 notes older than a year, with a rating less than -1
>>
>> The worst offender is:
>>
>> PHP: Cookies - Manual with -159 (not
>> sure why the website says -153)
>> PHP: Attributes overview - Manual
>> with -104
>>
>> We discussed this during one of our foundation meetings, and we propose:
>>
>> - to delete all notes with a rating less than -5 that are older than a
>> year.
>> - come up with a plan to crowd source going through the other thousands
>> of notes to see if they need to be deleted or integrated into the
>> actual text. Each documentation page now has a link to the XML source
>> (such as
>> doc-en/language/attributes.xml at master · php/doc-en · GitHub)
>>
>> Comments?
>
>This is something im both For and Against.
>
>On the *for* side, alot of these notes are negative rated for a reason, bad
>code, bad advice, incorrect usage, etc etc
>
>But on the *against* said is removing information, no matter how bad the
>code is or misunderstood, in my eyes no information should be removed. Let
>users see others' mistakes, so they dont repeat them.
>This is what the rating system is for. The only stuff that I wouldn't be
>against is clearly
>advertising/promotional/spam posts.
>
>If we had a thread system for these comments, so others can reply, they can
>point out mistakes/bad code/incorrect usage and those reading can learn
>what and what not to do.

Notes where never meant to be helpful to other developers. They were hints to the editors to include missing information, to add clarification, and sometimes to add new examples *into* the documentation, and then delete the note. This is less needed now as each page has a direct link to "report a bug" or the XML source.

The rating systems was another hint to the editors of the manual to see how wrong of helpful a hint for them was.

Walls of code with "special functions", or questions, or incorrect comments were always deleted without prejudice.

Help threads and discussions belong on the php-general list of somewhere else.

cheers
Derick

Jesus M. Castagnetto, Ph.D.
ORCID: ORCID
Github: jmcastagnetto (Jesus M. Castagnetto) · GitHub
LinkedIn: https://www.linkedin.com/in/jesuscastagnetto/
Web site: https://castagnetto.site/)

14

On Wed, Jul 10, 2024, at 12:24 PM, Bilge wrote:

On 10/07/2024 19:42, Derick Rethans wrote:

Notes where never meant to be helpful to other developers. They were hints to the editors

If that’s the case, why would they even be public?

I think Derick is over-stating things a bit. As I mentioned, the original intent was that the notes not be treated as precious, and that they lead to improvement of the actual text of the documentation. They 100% were not meant to be forums for discussion. They were meant to be temporary in nature.

They were public because it’s an open source project.

Jim

15

On Wed, 10 Jul 2024, Gina P. Banyard wrote:

On Wednesday, 10 July 2024 at 15:18, Derick Rethans <derick@php.net> wrote:

> We discussed this during one of our foundation meetings, and we propose:
>
> - to delete all notes with a rating less than -5 that are older than a
> year.
> - come up with a plan to crowd source going through the other thousands
> of notes to see if they need to be deleted or integrated into the
> actual text. Each documentation page now has a link to the XML source
> (such as doc-en/language/attributes.xml at master · php/doc-en · GitHub)
>
> Comments?

One question, should this possibly become a monthly cron job that
checks for the user notes and removes those that fall below the above
criterias?

I was indeed intending for this to become a recurring job. There is
already a script that (should) emails weekly the top-commented pages,
but it currently fails email delivery.

I have now fixed that
(The from address needs to be noreply@ as the phpdoc list doesn't allo… · php/web-master@f2add6e · GitHub),
and the result is at php.notes: Notes Status, 19992 total

cheers,
Derick

--
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: Xdebug: Support

mastodon: @derickr@phpc.social @xdebug@phpc.social

16

On Wed, 10 Jul 2024, Tim Düsterhus wrote:

On 7/10/24 16:18, Derick Rethans wrote:
> Comments?

For now I'm only asking to give me the time to go through the
ext/random stuff myself before the automated deletion is performed
(i.e. defer this until after feature freeze at least).

That will take no time, as there are no comments (at all) for the random
engine yet!

Only the older functional API has 7 with a score less than -5:

| function.array-rand | 2021-12-03 15:06:19 | 126659 | -7 |
| function.rand | 2020-10-05 11:07:56 | 125416 | -9 |
| function.openssl-random-pseudo-bytes | 2012-05-06 00:17:49 | 108550 | -9 |
| function.openssl-random-pseudo-bytes | 2018-02-24 16:08:49 | 122436 | -9 |
| function.random-bytes | 2018-05-25 00:06:34 | 122766 | -15 |
| function.rand | 2010-03-05 18:41:06 | 96583 | -16 |
| function.openssl-random-pseudo-bytes | 2017-10-31 17:18:05 | 121817 | -19 |

(And they are indeed delete worthy).

cheers,
Derick

17

On Wed, Jul 10, 2024, at 9:18 AM, Derick Rethans wrote:

Hi!

There are currently nearly 20000 notes in the documentation, with many
having a very high negative rating.

For example, there are:

1131 notes older than a year, with a rating less than -10
2339 notes older than a year, with a rating less than -5
5761 notes older than a year, with a rating less than -1

The worst offender is:

PHP: Cookies - Manual with -159
(not sure why the website says -153)
PHP: Attributes overview - Manual
with -104

We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a
  year.
- come up with a plan to crowd source going through the other thousands
  of notes to see if they need to be deleted or integrated into the
  actual text. Each documentation page now has a link to the XML source
  (such as doc-en/language/attributes.xml at master · php/doc-en · GitHub)

Comments?

I had proposed something similar on the docs list a while back, and some folks were squeamish. I'm still in favor, though, including making it a regular cron job.

I've also done a fair bit of triage of incoming comments, and in practice we delete most of them. Extremely few of the comments that come in are improvements for the docs. They're people using notes as a help forum, or a blog to show off their utility functions, or write buggy polyfills that get corrected 4 times by other people. And that's excluding the obvious spam.

I have at times gone through and cleaned up an individual page, usually knocking the number of comments down from 40-something to 3-ish. Most get deleted, a small number turn into PRs.

I think I have personally found a note useful... once, maybe twice, in as far back as my memory goes.

I would be perfectly OK with just turning notes off entirely, though we should still triage them for any gems worthy of turning into PRs. But beyond that, let people just file a PR. Making notes readonly would get a+1 from me.

--Larry Garfield

18

On Wed, 10 Jul 2024, Derick Rethans wrote:

We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a
  year.

As general consensus was that this correct, I will be creating a script
for this.

One of the other suggestions was to also have a public list to show all
notes with the highest or lowest rating, and add these to the weekly
status report (like php.doc: Notes Status, 19841 total). I will
be creating a script for this too.

- come up with a plan to crowd source going through the other
  thousands of notes to see if they need to be deleted or integrated
  into the actual text. Each documentation page now has a link to the
  XML source (such as
  doc-en/language/attributes.xml at master · php/doc-en · GitHub)

Hopefully, this is going to get some work behind it soon too.

cheers,
Derick

--
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: Xdebug: Support

mastodon: @derickr@phpc.social @xdebug@phpc.social

19

On 23/08/2024 11:34, Derick Rethans wrote:

On Wed, 10 Jul 2024, Derick Rethans wrote:

We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a
   year.

As general consensus was that this correct, I will be creating a script
for this.

What is to stop a malicious actor committing a distributed downvote and wiping the entire notes database?

Cheers, Bilge

20

On Fri, Aug 23, 2024, at 15:05, Bilge wrote:

On 23/08/2024 11:34, Derick Rethans wrote:

On Wed, 10 Jul 2024, Derick Rethans wrote:


We discussed this during one of our foundation meetings, and we propose:

- to delete all notes with a rating less than -5 that are older than a 
  year.


As general consensus was that this correct, I will be creating a script 
for this.

What is to stop a malicious actor committing a distributed downvote and wiping the entire notes database?

Cheers, Bilge

I imagine they have a snapshot from before it was discussed.

— Rob