Thanks Lukas for the continued effort on this topic. You're basically stumbling on a recurring problem that we have here at PHP-FIG: we don't have a way to stipulate a "living document", something that is similar to a PSR but can evolve.
IMHO this could actually work if we write down a new bylaw that handles this case, and it would solve similar issues like the coding standard (see PSR-12) where the PSR can't keep up with how fast the language is evolving. I'll give this some more thought and try to find a way to draft a bylaw that encapsulates a basic solution to this. Il giorno sabato 8 agosto 2020 alle 14:00:56 UTC+2 Lukas Kahwe Smith ha scritto: > > On Wed, 15 Jul 2020 at 17:49, Lukas Kahwe Smith <sm...@pooteeweet.org> > wrote: > >> Aloha, >> >> First up Chris thank you for your input specifically. >> >> Happy to see so many voices of support as well. >> >> In general: Who would be motivated to work with me on shaping a proposal? >> Please contact me directly via slack, email, twitter (@lsmith) .. >> >> Note: For now I would put the scope on inclusive language only. However I >> think in parallel work could also be done on maybe looking at other sources >> for issues in naming like the Events example I mention. >> > > Sorry for the long silence. I am still very much committed the the topic. > > From the feedback I got here, on FIG slack and other places there were > quite a few voices that feel like a PSR isn’t the right format. I therefore > decided to approach the topic more as “what would I as a > developer/documentor/etc need” to more easily be able to use inclusive > language? > > Jenny Wong shared with me documentation they created at the company she > works at: > https://engineering.hmn.md/standards/naming-things/ > > This document tries to essentially cover the general considerations, some > concrete examples but then links to additional resources. > > Most notably it links to the following guide by google which seems to be > the most complete and well structured document I found on the topic: > https://developers.google.com/style > > My only criticism is that it might be a bit overwhelming. So I think it is > specifically something people that act as editors for documentation should > be fully aware of but as a general resource I fear it could lead to people > giving up as it feels too big an effort to make any difference. > > So I think I like the approach of giving an overview, I also like giving > detailed examples but I would then add a bigger section which can be read > in 5-10mins with less details that should be enough to make a material > impact and then linking other more detailed resources at the bottom. > > Now this approach indeed might not lend itself to a PSR which I guess is > the type of document that is more definitive and where compliance can be > determined in a more binary fashion. > > I do however want a document that actively encourages PHP projects to > adopt it. > > I also do want to also offer some sort of method to more easily validate > (or at list get a list of things to review in detail) both code and > documentation ( > https://github.com/OskarStark/doctor-rst/blob/master/src/Rule/BeKindToNewcomers.php). > > Maybe also discussions on their chat ( > https://github.com/keoghpe/alex-slack) and in pull requests. > > Especially for chat/PRs I realize that people will likely tend towards > becoming defensive and others might get annoyed by the disruption if the > comments are done inside the normal discussion. As such the best approach > might be a throttled (opt-in?) feedback via a separate channel (DM, email). > See also > https://github.com/keoghpe/alex-slack/pull/2 > > regards, > Lukas > >> > > -- > regards, > Lukas > -- You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group. To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/63e915c1-eeae-49f9-b191-62549db4f9d7n%40googlegroups.com.
