Addressing the Reader in the Second Person?

[jzf2101]

@yuvipanda has written a documentation guide and provided guidelines for addressing hypothetical people. As a followup, how do people think of the practice of writing the documentation in the second person > you? We have this practice in other projects.

[yuvipanda]

Hey @jzf2101! Can you gimme some examples of what this would entail? I'm not sure I understand.

[jzf2101]

From https://github.com/jupyterhub/the-littlest-jupyterhub/blob/master/docs/contributing/docs.rst

Writing style
When using pronouns in reference to a hypothetical person, such as "a user with a running notebook", gender neutral pronouns (they/their/them) should be used. Instead of:

he or she... use they.
him or her... use them.
his or her... use their.
his or hers... use theirs.
himself or herself... use themselves.

I think this is a reasonable policy. Based on what I've read from the actual documentation, we don't tend to address the reader in the 3rd person. It seems as if we typically address the reader in the second person. Example:

By the end of this tutorial, you should have a JupyterHub with some admin users and a user environment with packages you want installed running on Google Cloud.

In https://github.com/jupyterhub/the-littlest-jupyterhub/blob/master/docs/install/google.rst

I'd like to include an amendment to the above description of the third person description similar to:

The documentation should be written in the second person, referring to the reader as “you” and not using the first person plural “we.” The author of the documentation is not sitting next to the user, so using “we” can lead to frustration when things don’t work as expected.

https://jupyterlab.readthedocs.io/en/latest/developer/documentation.html

We don't have to use this exact language- I think that emphasizing use of the 2nd person over the 3rd deals with some confusion over how to write the docs.