-
-
Notifications
You must be signed in to change notification settings - Fork 31.8k
Usage of first-person pronouns in documentation #92033
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
I don't see why we care about changing this. It reads well and allows a personal touch like a guided tour. |
There is more of this. See #62480. |
Borrowing some of the discussion on Diataxis, I think whether first-person pronouns belong in documentation depends on how the documentation is structured. If it is the case how-to/guides and tutorials can be personal, and references impersonal (say like Wikipedia articles), then it seems acceptable that a page of documentation (pages under If it's the case that documentation shouldn't have first-person pronouns, then perhaps documentation should explicitly split these guides, tutorials, and references into their own pages, somewhat like logging. |
I'm with Raymond; I don't think anything needs changing here. |
If a section of the doc was written in first person I'd agree that it would read like a personal guide, but doesn't it read a bit oddly and seem out of place when there's only one instance of a first-person perspective? |
There's also a lot of "we" in this document. |
I see I see, that makes a lot more sense, thanks. |
Documentation
On line 2525 of the documentation, first-person narration is used for one single line. The entire doc is written using second person narration throughout, excluding this singular typo.
Current line:
Before I explain how auto-speccing works, here’s why it is needed.
Proposed update line:
Before explaining how auto-speccing works, it is important to understand why it is needed.
The text was updated successfully, but these errors were encountered: