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