Re: Coding standard for examples in documentation

On Mon, Oct 14, 2024, at 12:43 PM, Jim Winstead wrote:
> The coding style for the documentation has been documented to be the 
> PEAR coding standard (https://pear.php.net/manual/en/standards.php) 
> which is more than a little out-dated at this point. This has come up 
> in at least a few PR reviews recently.
>
> Any objections to changing this to the PER Coding Style 2.0 
> (https://www.php-fig.org/per/coding-style/)?
>
> I don't think we should be aggressive about going in and updating 
> existing examples, but should strive to make sure that new and changed 
> examples are in sync with the new CS through reviews and perhaps 
> automated checks.
>
> (I guess the last time this came up it got bogged down in the quagmire 
> about whether using a PHP-FIG standard implied some sort of favoritism 
> or endorsement or whatever. Maybe we'll have to open a RFC on 
> internals@ to address this documentation issue? 
> https://news-web.php.net/php.doc/969387610)

Here is a PR implementing this change against the updated contribution guide that will be live on doc.php.net soon.

https://github.com/php/doc-base/pull/167

In a different PR to update a bit about grammar in the style guidelines, I added some text about how these style guidelines are supposed to be applied:

https://github.com/php/doc-base/pull/168

tl;dr Guidelines apply to new docs and docs being revised where it won't overly burden translators.

Jim