• /
  • Log in

Users/roles-related language guidelines

This doc explains required styles and recommended phrasings for user-related terminology on the New Relic One user model.

Note about user models

This style guide applies to the New Relic One user model, not the original user model. Even though both user models share certain terms (such as Admin), this is an entirely different user model with a very different structure, recommended phrasings, and style. To understand user model changes and differences, see Overview of user model changes.

The original user model will be increasingly deprecated, so we shouldn't need to talk much about that user model or update those docs.

Styles and formatting

Here are some user-related styles and formats for user-related language for the New Relic One user model:

Category

Example use

Styles and tips

User type (basic user vs full user)

"If you’re a full user..."

Lower case, no style.

Note that it can sometimes be awkward when "basic user" is in front of a noun. For example: "To learn about basic user capabilities..." can sound like you're talking about user capabilities that are basic. To avoid this, rephrase to be more clear and/or link to the user type doc section from "basic user" or "full user."

Roles

"You must be in a group that has the Billing user role."

Sentence case, bold.

This phrasing is meant to cover all cases where a user is in a group that has that role, whether that group is a default group (Admin or User) or a custom group that has had that role assigned.

We recommend linking to the standard roles doc, which lists and defines the roles, and also explains how these roles are related to the default groups (Admin and User).

Default groups

"When adding a user, add them to the Admin group."

Sentence case, bold.

We recommend linking to the explanation of default groups for more context.

Philosophy for user permissions/roles language

Before writing about permission-related requirements, it may help if you learn about the relationships between groups, roles, and capabilities.

The following recommendations for permissions-related documentation philosophy applies primarly for documenting our New Relic One user model, not our original user model.

Don't document requirements for user type or group

We don't document restrictions related to user type (basic vs. full user) or default groups. Some information about why that is:

  • Basic vs. full users: We don't document restrictions related to user type (basic vs. full). This is because UI views that are off-limits for basic users have explanations and upsell information, so this will mostly be self-evident. And because basic user limitations are so widespread, we would be documenting that in a huge number of locations if we took the approach of documenting basic user restrictions.
    • API docs exception: Because APIs are not as obvious and transparent as the New Relic UI, we should document any requirements that SMEs think are relevant, which may include user type. Attempt to put any requirements for using an API in a single location, and not spread them throughout the docs.
  • Default user groups: We don't explain restrictions related to user groups (e.g., our default groups Admin and User). This is because the actual mechanism causing the restriction is not due to the group, but to the role assigned to that group (and at a more granular level, due to the capabilities associated with that role).

If you have questions about user type, user group, and user roles, see the User model doc.

Document requirements for relevant role or capability

When thought necessary, we should document any roles or capabilities that gate access to a feature. A few notes on this:

  • Note that we don't document requirements related to user type or group. While there are certain roles and capabilities that user type gives access to, if the requirement is mainly related to user type, we shouldn't document that.
  • Note that our standard roles are just aggregations of capabilities. This means that several standard roles can all have several of the same capabilities. In that case, in order to be more specific, you'd reference the capabilities, not the role. It is okay to use general, informal language when referencing capabilities, as is shown in the example below.
  • Some standard roles (like Billing user and Organization manager and Authentication domain manager) have capabilities that aren't exposed in the UI to customers, so this means that in those cases we'd have to just reference the role and not a specific capability.

Examples:

Document requirements for both original and new user model

If you're including requirements about New Relic One user model roles or capabilities, you may also need to include details about the original user model. Here's an example of how to do that.

Permissions requirements differ depending on your user model:
* For users on the [original user model](/docs/accounts/original-accounts-billing/original-product-based-pricing/overview-changes-pricing-user-model/#user-models): the [**Data retention manager** role](/docs/accounts/original-accounts-billing/original-users-roles/users-roles-original-user-model/#roles).
* For users on the [New Relic One user model](/docs/accounts/original-accounts-billing/original-product-based-pricing/overview-changes-pricing-user-model/#user-models): the [**Billing user** role](com/docs/accounts/accounts-billing/new-relic-one-user-management/new-relic-one-user-model-understand-user-structure/#standard-roles).

For more about role language guidelines, see the styles table.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.