Make WordPress Core

Opened 18 months ago

Closed 13 months ago

Last modified 13 months ago

#57052 closed enhancement (fixed)

Revise use of "we" in comments to second person point of view

Reported by: ironprogrammer's profile ironprogrammer Owned by: audrasjb's profile audrasjb
Milestone: 6.3 Priority: normal
Severity: normal Version:
Component: Text Changes Keywords: has-patch
Focuses: Cc:

Description

Adjusts comments using "we" (first person point of view) to preferred second person point of view, as outlined in Make/Docs:

Follow-up to #46057.

Change History (26)

This ticket was mentioned in PR #3593 on WordPress/wordpress-develop by @ironprogrammer.


18 months ago
#1

  • Keywords has-patch added
  • Replaces first-person usage of "we" with second person point of view.
  • Also makes small clarification adjustments where voice is much too casual and lacks clear context, especially for non-native English speakers.

This PR focuses on files in the WordPress root directory.

Trac ticket: https://core.trac.wordpress.org/ticket/57052

This ticket was mentioned in PR #3595 on WordPress/wordpress-develop by @ironprogrammer.


18 months ago
#2

DRAFT -- work in progress

  • Replaces first-person usage of "we" with second person point of view.
  • Also makes small clarification adjustments where voice is much too casual or lacks clear context, especially for non-native English speakers.

This PR focuses on files in the WordPress wp-admin directory.

Trac ticket: https://core.trac.wordpress.org/ticket/57052

#3 follow-up: @jorbin
18 months ago

Alot of the casual language is very intentional and should not be removed.

@ironprogrammer commented on PR #3593:


17 months ago
#4

Just one suggestion that I'm not precious about. LGTM with or without the suggestion 👍

Thanks, @costdev! Change committed.

#5 in reply to: ↑ 3 @ironprogrammer
17 months ago

Thanks, jorbin:

Alot of the casual language is very intentional and should not be removed.

Understood, and I agree. My saying "much too casual" in the PR description was too euphemistic. So to better describe what I meant, here's an example where the internal dialog-style may confuse things 😁:

Original (introduced):

        /*
         * We're going to redirect to setup-config.php. While this shouldn't result
         * in an infinite loop, that's a silly thing to assume, don't you think? If
         * we're traveling in circles, our last-ditch effort is "Need more help?"
         */

Revised (ba67ff2):

        // Redirect to setup-config.php.

#6 @SergeyBiryukov
17 months ago

  • Milestone changed from Awaiting Review to 6.2

Thanks for the ticket! The suggested edits look good to me at a glance.

@ironprogrammer commented on PR #3593:


17 months ago
#7

Thanks for the reviews, @SergeyBiryukov! I appreciate it!

#8 @SergeyBiryukov
17 months ago

In 54866:

Docs: Revise comments using “we” in WordPress root directory files.

This updates some inline comments to better match the guidelines and recommendations set forth in the make/core and make/docs handbooks:

In general, use second person in your documentation. Second person depicts a friendly tone, with a perfect focus on the reader. In addition to this, directly addressing the reader helps avoid passive voice; thereby preventing unwanted confusion.
...
the word “we” should be avoided (...) unless its made very clear which group is speaking.

Includes:

  • Replacing first-person usage of "we" with second person point of view.
  • Making small clarification adjustments where the voice is much too casual or lacks clear context, especially for non-native English speakers.

References:

Follow-up to [2176], [3430], [4676], [6009], [7991], [12688], [12762], [26008], [28978], [44488], [44962], [51979], [53131], [53132], [53156], [53131], [54200].

Props ironprogrammer, costdev, jorbin, SergeyBiryukov.
See #57052.

@SergeyBiryukov commented on PR #3593:


17 months ago
#9

Thanks for the PR! Merged in r54866.

This ticket was mentioned in Slack in #core by mukeshpanchal27. View the logs.


15 months ago

#11 @mukesh27
15 months ago

  • Keywords reporter-feedback added

This ticket was discussed in the recent bug scrub.

One PR has been merged, but the other is still in draft. @ironprogrammer's second PR still needs some work? Do you think it will be ready for review before beta?

Props to @costdev

This ticket was mentioned in Slack in #core by costdev. View the logs.


15 months ago

#13 @costdev
15 months ago

  • Keywords reporter-feedback removed
  • Resolution set to fixed
  • Status changed from new to closed

This ticket was discussed during the bug scrub. PR 3595 will not be ready for 6.2 Beta 1 on February 7th, and can be addressed in a follow-up ticket in a future release.

Closing this ticket as fixed in 6.2.

Additional props: @audrasjb

#15 @majaloncar
13 months ago

We are at WordCamp Switzerland and during the contributor day JB Ausdras identified the bug and we as the team resolved it.

#16 @audrasjb
13 months ago

  • Milestone changed from 6.2 to 6.3
  • Resolution fixed deleted
  • Status changed from closed to reopened

Indeed wee missed (at least) one occurrence!
Reopening so we can hopefully fix this for WP 6.3 :)

#18 @leamcaleese
13 months ago

We are at WordCamp Switzerland and during the contributor day. JB Ausdras identified the bug and we as the team resolved it.

#20 @annebovelett
13 months ago

I'm at WordCamp Switzerland, at the contributor day, and FINALLY learned how to do this. :-)

#21 @audrasjb
13 months ago

Note: We used this ticket for learning purpose as part of WordCamp Switzerland, a big thank you to our three heroes of the day! @annebovelett, @majaloncar @leamcaleese :)

#22 @NekoJonez
13 months ago

I honestly think tickets like these should be one of the last commits no? What good would a commit now do if later in the 6.3 dev cycle another we is added...?

#23 @audrasjb
13 months ago

  • Owner set to audrasjb
  • Resolution set to fixed
  • Status changed from reopened to closed

In 55646:

Docs: Revise comments using “we” in various docblocks.

This updates some inline comments to better match the guidelines and recommendations set forth in the make/core and make/docs handbooks:

In general, use second person in your documentation. Second person depicts a friendly tone, with a perfect focus on the reader. In addition to this, directly addressing the reader helps avoid passive voice; thereby preventing unwanted confusion. The word “we” should be avoided (...) unless its made very clear which group is speaking.

References:

Follow-up to [2176], [3430], [4676], [6009], [7991], [12688], [12762], [26008], [28978], [44488], [44962], [51979], [53131], [53132], [53156], [53131], [54200], [54866].

Props majaloncar, leamcaleese, annebovelett.
Fixes #57052.

Note: See TracTickets for help on using tickets.