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/CAEFKHaEbyKOQnPQSykkPd60S9ZdbT0MFw4xC0qHC0AnioYYxOQ%40mail.gmail.com.
