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:
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.
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: