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

Remove references to "you" and "your" in API docstrings #959

Closed
benhoyt opened this issue Jul 3, 2023 · 2 comments · Fixed by #1003
Closed

Remove references to "you" and "your" in API docstrings #959

benhoyt opened this issue Jul 3, 2023 · 2 comments · Fixed by #1003
Assignees
Labels
docs Improvements or additions to documentation small item

Comments

@benhoyt
Copy link
Collaborator

benhoyt commented Jul 3, 2023

Per Jon's comment here, we should clean up the style in our API docstrings to avoid using "you".

@benhoyt benhoyt added docs Improvements or additions to documentation small item labels Jul 3, 2023
@tonyandrewmeyer
Copy link
Contributor

@benhoyt are we specifically avoiding you/your referring to the developer, or also when it's used to refer to the charm/unit/etc?

For example:

You can use this to determine (for example) whether you are the departing unit.

The first "you" is clearly one we want to change, for example to:

Use this to determine (for example) whether you are the departing unit.

Do we also want to remove the second "you" as well? For example to:

Use this to determine (for example) whether the caller is the departing unit.

Or, another example:

This might be your unit, another unit of your application, or a unit of another application that you are related to.

This doesn't match the main case referenced in #953 where we want to use imperative language. Would we change it to, for example:

This might be the local unit, another unit in the same application, or a unit of another application via an integration.

(Secondary question from that example: when working on things like this, do we adjust to say "integration" rather than "relation"?)

@benhoyt
Copy link
Collaborator Author

benhoyt commented Sep 20, 2023

I would say we do want to remove all those usages of "you", yeah, for clarity and consistency. For one, the person reading might not be the charm author. Perhaps:

Use this to determine (for example) whether this unit is the departing one.

This might be the current unit, another unit of this application, or a unit of an application this charm is related to.

I don't think we want to change all instances to "integration" -- at least let's leave that for another PR. I'm not actually sure "related to" is incorrect there; "integrated with" feels clumsy, but maybe it is what we've settled on. You could also ask that on the Juju Mattermost channel (maybe ping @tmihoc, the Juju team's docs person). Either way, let's leave for a separate PR for easier review.

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

Successfully merging a pull request may close this issue.

2 participants