Skip to content

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

Closed
AnnaElshayeb opened this issue Apr 28, 2022 · 7 comments
Closed

Usage of first-person pronouns in documentation #92033

AnnaElshayeb opened this issue Apr 28, 2022 · 7 comments
Labels
docs Documentation in the Doc dir

Comments

@AnnaElshayeb
Copy link

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.

@rhettinger
Copy link
Contributor

I don't see why we care about changing this. It reads well and allows a personal touch like a guided tour.

@serhiy-storchaka
Copy link
Member

There is more of this. See #62480.

@slateny
Copy link
Contributor

slateny commented Apr 29, 2022

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 /library) that blends guides, tutorials, and references may have a blend of first- and third-person pronouns, as in the referenced unittest.mock.

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.

@JelleZijlstra
Copy link
Member

I'm with Raymond; I don't think anything needs changing here.

@slateny
Copy link
Contributor

slateny commented May 1, 2022

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?

@JelleZijlstra
Copy link
Member

There's also a lot of "we" in this document.

@slateny
Copy link
Contributor

slateny commented May 1, 2022

I see I see, that makes a lot more sense, thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants