Skip to content
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

Usage of first-person pronouns in documentation #92033

Open
AnnaElshayeb opened this issue Apr 28, 2022 · 3 comments · May be fixed by #92035
Open

Usage of first-person pronouns in documentation #92033

AnnaElshayeb opened this issue Apr 28, 2022 · 3 comments · May be fixed by #92035
Labels
docs

Comments

@AnnaElshayeb
Copy link

@AnnaElshayeb AnnaElshayeb commented Apr 28, 2022

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.

@AnnaElshayeb AnnaElshayeb added the docs label Apr 28, 2022
@rhettinger
Copy link
Contributor

@rhettinger rhettinger commented Apr 29, 2022

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

@serhiy-storchaka serhiy-storchaka commented Apr 29, 2022

There is more of this. See #62480.

@slateny
Copy link
Contributor

@slateny 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.

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

Successfully merging a pull request may close this issue.

4 participants