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
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 -1The 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 -104We 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?
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
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?
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
(https://github.com/php/web-master/commit/f2add6e1ff11332c56177ca295d4fbf2f4ccbd49),
and the result is at https://news-web.php.net/php.notes/221419
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
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 -1The 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 -104We 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.ioAuthor of Xdebug. Like it? Consider supporting me:
https://xdebug.org/supportmastodon: @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.
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 -1The 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 -104We 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?
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 etcBut 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
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
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
Notes where never meant to be helpful to other developers. They were
hints to the editorsIf 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
Cheers,
Christoph
Hi
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
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
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?
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
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 https://news-web.php.net/php.doc/969388402). 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
https://github.com/php/doc-en/blob/master/language/attributes.xml)
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: https://xdebug.org/support
mastodon: @derickr@phpc.social @xdebug@phpc.social
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
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