On 10 July 2024 18:47:07 BST, fennic log <fennic...@gmail.com> wrote: >On Wed, 10 Jul 2024 at 15:18, Derick Rethans <der...@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? > >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
