On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:
>One thing I miss from my PHP days (I know - script languages - Ugh), is having public comments below each manual page.
Having the public post examples, gotchas, and other helpful information made a world of difference in learning the PHP language, all the while having the "source of truth" directly above.
Just suggesting that it might help increase adoption rates (PHP is very popular). Managing comments does take time, but then so does managing this forum.
Anyway, no ideas are bad ideas, so I felt I should post. I hope it is helpful.
Andrei’s alternative one-page-per-function documentation had a user comment section on every page at one stage. IIRC that feature wasn’t used much and when it was the comment wasn’t very useful.
But we have a method for anybody to improve any page of the documentation with examples, See_Also links and (if you ask me) even smart suggestions like this one: it is the “improve this page” link at the top of every page.
This is what I would suggest if the documentation doesn’t give an answer right away: ask on the learn forum, then come back to the documentation and see if that additional knowledge can be incorporated in the text. I think this is a good way to make things better.
— Bastiaan.