Re: Notes Status, 23867 total
| From: | Jesus Castagnetto | Date: | Sun, 12 Jun 2022 06:43:03 +0000 |
| Subject: | Re: Notes Status, 23867 total | ||
| References: | 1 2 3 | Groups: | php.doc |
| Request: | Send a blank email to phpdoc+get-969388129@lists.php.net to get a copy of this message | ||
Hello
Even I am no longer active in the documentation of PHP (for eons), but I recall that there were some
rough guidelines to deal with notes (http://doc.php.net/tutorial/user-notes.php)
With respect to the relevance today of having notes. Back in the early days, late 90s-early 00s,
implementing the notes system was a good idea, as there were no alternatives like there are today.
Hopefully the new generation of doc editors (you all :-) will come up with some good solution or
replacement altogether. Change is constant and if it is for the better, it will be welcomed by the
community.
Cheers.
> On 2022-06-12 08.30 Tiffany <tiffany.k.taylor@gmail.com> wrote:
>
>
>
>
> On Sat, Jun 11, 2022, 10:49 PM Robert Woodall <me@rwoodall.com
> mailto:me@rwoodall.com> wrote:
>
> > Instead of spending so much time on these notes, is there a more actionable method such as
> > Q/A like Stackoverflow? Or maybe an inline commit edit approval method to just improve the docs
> > naturally instead of forcing non natural collaboration? I myself think the examples are awful and
> > the comments probvide better ones. Could we encourage the policy we want with new functionality?
> >
> > It seems too hard to contribute I guess.
> >
>
>
> There's been discussion about nuking negative notes, but I think the consensus was
> "not right now" or at least waiting until a time in the future. The general idea behind
> the comments section is that the higher quality comments are rolled into the manual page, and the
> comments are deleted. Ideally, the comments section stays relatively clean. However, as you can
> tell, it's easy for pages to have a seemingly overwhelming number of comments to go through,
> especially since there are numerous manual pages.
>
> If you notice an example on a page is worse than an example contained in a comment, I encourage
> you to submit a PR and either including the better example on the page, or replacing the worse
> example altogether.
>
>
--
Jesus M. Castagnetto, Ph.D. <jesus@castagnetto.com mailto:jesus@castagnetto.com>
Web site: https://castagnetto.site/
Github: https://github.com/jmcastagnetto
LinkedIn: https://www.linkedin.com/in/jesuscastagnetto/
ORCID: https://orcid.org/0000-0002-7188-1605