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.

Sign up for GitHub

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

Update grammar.adoc with guidance on inanimate users #495

Merged
merged 13 commits into from
Aug 7, 2024
Merged

Update grammar.adoc with guidance on inanimate users #495

Changes from 9 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
e9e888b
Update grammar.adoc with guidance on inanimate users
jafiala Jun 28, 2024
815ebd1
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 23, 2024
408ce1d
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 23, 2024
c5b3a93
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 23, 2024
5d19658
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 23, 2024
7c32e1f
Reorder examples for users
jafiala Jul 23, 2024
550cbc7
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 29, 2024
cceea76
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 29, 2024
6ecce61
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 29, 2024
ab68a3b
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 29, 2024
49a4b82
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Jul 29, 2024
2b04791
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Aug 6, 2024
4456325
Update supplementary_style_guide/style_guidelines/grammar.adoc
jafiala Aug 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions supplementary_style_guide/style_guidelines/grammar.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,4 +128,30 @@ Avoid long introductions and unnecessary context. Shorten unnecessarily long sen
=== Principle 5: Error recovery, verification, and troubleshooting
Recognize that people make mistakes and need to verify that they have completed a task. Be sure to include troubleshooting, error recovery, and verification steps.

[[users]]
== Users
In most cases, the word "user" refers to a person or a person's user account, and therefore would be considered animate. In these cases, use animate personal pronouns such as "who".
jafiala marked this conversation as resolved.
Show resolved Hide resolved
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking out aloud here. Do we want to differentiate them like the "task performer" vs "role references"?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I'm not sure I understand what you mean here.

Do you mean that we sometimes refer to "users" as those who perform the tasks (i.e. reader)?

And Linux and SELinux users and similar would be role references?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was trying to suggest some direct guidelines that would help writers make a decision. I was thinking something on the lines of:
"Task performers" -> Use animate
"Role references"-> Use inanimate

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've thought about this, but I think this is too simple a recommendation. We can refer to personal users even when they are not task performers. In fact, we should typically refer to task performers as "you" and write directly to them.

Also, we should primarily write around role references instead of using the inanimate pronouns.

So I think the current recommendation is more accurate:

In these specific cases, and only if you cannot write around it, you can refer to these inanimate users with inanimate personal pronouns such as "that".

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good!


However, in certain technical cases, these users are not persons but instead user accounts or more abstract concepts. For example, Linux users such as `root` and `guest` do not relate to any person. Applications and services might run as specific Linux users with no person controlling them. SELinux users such as `user_u` or `sysadm_u` are identifiers of one or multiple Linux users for access control purposes.
jafiala marked this conversation as resolved.
Show resolved Hide resolved

In these specific cases, and only if you cannot write around it, you can refer to these inanimate users with inanimate personal pronouns such as "that".

.Examples
jafiala marked this conversation as resolved.
Show resolved Hide resolved
* Animate user
+
image:images/no.png[no] Experienced _users that_ can configure their own systems....
jafiala marked this conversation as resolved.
Show resolved Hide resolved
+
image:images/yes.png[yes] _Users who_ want to install their own packages....
jafiala marked this conversation as resolved.
Show resolved Hide resolved

* Inanimate user
+
image:images/no.png[no] A Linux user has the restrictions of the _SELinux user who_ it is assigned to.
+
image:images/no.png[no] A Linux user has the restrictions of the _SELinux user_ to _whom_ it is assigned.
+
image:images/yes.png[yes] Specify a _user that_ is allowed to perform the requested action.
+
image:images/yes.png[yes] A Linux user has the restrictions of the _SELinux user that_ it is assigned to.
Comment on lines +148 to +154
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... it is assigned to. Here it is inanimate and I believe it is referring to A Linux user. But IIUC, Linux user is still animate here, in which case we might have to say ..they are assigned to. instead. Feel free to correct me here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, the Linux user here does not refer to a person who uses linux, but to the Linux user account, like guest.

Copy link

@snarayan-redhat snarayan-redhat Jul 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so we may want to emphasize on that too since it is overlooked currently.
e.g.
image:images/no.png[no] A _Linux user_ has the restrictions of the _SELinux user who it is_ assigned to.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, I tried to emphasize only the parts of speech to which the pronouns point (and the pronouns themselves). I think emphasizing this user would make it less clear, because no pronoun refers to it.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... it is assigned to. Here it is inanimate and I believe it is referring to A Linux user. But IIUC, Linux user is still animate here, in which case we might have to say ..they are assigned to. instead. Feel free to correct me here.

I thought it refers to Linux user



// TODO: Add new style entries alphabetically in this file
Loading