Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:124366
Date: Wed, 10 Jul 2024 19:42:43 +0100
To: internals@lists.php.net, fennic log <fenniclog@gmail.com>
CC: PHP Documentation List <phpdoc@lists.php.net>,
 PHP Developers Mailing List <internals@lists.php.net>
Subject: Re: [PHP-DEV] Negatively Voted Notes
User-Agent: K-9 Mail for Android
In-Reply-To: <CAO__Xv6WtxS8xFHf7tzQ3vW111CydjDaNCJ26xBVEUmLhtPgeA@mail.gmail.com>
References: <f8289b49-e163-ed36-c67b-bb08d1069638@php.net> <CAO__Xv6WtxS8xFHf7tzQ3vW111CydjDaNCJ26xBVEUmLhtPgeA@mail.gmail.com>
Message-ID: <41A5CC28-2C29-4013-98BE-DB81102D702E@php.net>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain;
 charset=utf-8
Content-Transfer-Encoding: quoted-printable
From: derick@php.net (Derick Rethans)

On 10 July 2024 18:47:07 BST, fennic log <fenniclog@gmail=2Ecom> wrote:
>On Wed, 10 Jul 2024 at 15:18, Derick Rethans <derick@php=2Enet> wrote:
>
>> Hi!
>>
>> There are currently nearly 20000 notes in the documentation, with many
>> having a very high negative rating=2E
>>
>> 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=2Ephp=2Enet/manual/en/features=2Ecookies=2Ephp#128286 with =
-159 (not
>> sure why the website says -153)
>> https://www=2Ephp=2Enet/manual/en/language=2Eattributes=2Eoverview=2Eph=
p#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=2E
>> - 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=2E Each documentation page now has a link to the XML sour=
ce
>>   (such as
>> https://github=2Ecom/php/doc-en/blob/master/language/attributes=2Exml)
>>
>> Comments?
>
>This is something im both For and Against=2E
>
>On the *for* side, alot of these notes are negative rated for a reason, b=
ad
>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=2E =
Let
>users see others' mistakes, so they dont repeat them=2E
>This is what the rating system is for=2E The only stuff that I wouldn't b=
e
>against is clearly
>advertising/promotional/spam posts=2E
>
>If we had a thread system for these comments, so others can reply, they c=
an
>point out mistakes/bad code/incorrect usage and those reading can learn
>what and what not to do=2E

Notes where never meant to be helpful to other developers=2E They were hin=
ts to the editors to include missing information, to add clarification, and=
 sometimes to add new examples *into* the documentation, and then delete th=
e note=2E This is less needed now as each page has a direct link to "report=
 a bug" or the XML source=2E=20

The rating systems was another hint to the editors of the manual to see ho=
w wrong of helpful a hint for them was=2E=20

Walls of code with "special functions", or questions, or incorrect comment=
s were always deleted without prejudice=2E=20

Help threads and discussions belong on the php-general list of somewhere e=
lse=2E=20

cheers=20
Derick=20