This doc explains required styles and recommended phrasings for user-related terminology on the New Relic One user model.
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.
Here are some user-related styles and formats for user-related language for the New Relic One user model:
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."
"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).
"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.
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.
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.
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.
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.
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.