• /
  • ログイン
  • 無料アカウント

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 an entirely different structure, recommended phrasings, and style. To understand user model differences, see Overview of user models.

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

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. core user vs. full platform user)

Example use: If you’re a full platform user, you can...

Lower case, with no style applied. We took this simple approach because the user type names are short names, easily understood without formatting or capitalization, and because this gives us the ability to refer to user types as plurals (e.g., "your organization's basic users can...")

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 from the mention of the user type.

Roles

Example use: This capability is available for the All product admin role.

Preferred: sentence case, bold. Alternatively, instead of bold, you can use italics or code-formatting: as long as it's clear that we're referring to something that has a definite, exact name.

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

Default groups

Example use: When adding a user, you can add them to either the default Admin or User groups, or a custom group if you have any.

For docs site, use sentence case and bold. Alternatively, for non-docs-site styling, you can use italics or code-formatting: as long as it's clear that we're referring to something that has a definite, exact name. The words 'admin' and 'user' are generic, general words, so using formatting to indicate that we're referencing specific terms is important.

When referencing the default groups, we recommend linking to the explanation of default groups.

Capabilities

Example use: The ability to do this is governed by the "modify APM settings" capability.

One way to reference a capability is by using quotes as shown in the example here, but we don't have firm rules on how to reference capabilities. One reason for this is that capabilities don't have specific proper names and are more informal. To see what we mean, see the screenshot of the capabilities UI table. The rows in the capabilities table have a heading (like "APM"), and refer to a feature (like "Application settings"), and have columns referencing more granular abilities (like "Create" or "Delete"). For this reason, we don't have a firm rule but the goal is simply to try to make it clear which capability you're referencing.

Philosophy for user permissions/roles language

Before writing permission-related requirements for docs or similar use cases, you should read about user management concepts.

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

Notes on documenting user type or group as requirements

For most docs for specific New Relic features, we don't document restrictions related to user type (basic user, core user, full platform user) or default groups. The primary place where we explain what's available by user type is in the 'User type' documentation. Some reasoning about why that is:

  • User type: The place we document capabilities related to user type is the primary 'User type' doc. This means that we don't need to put user type requirements in every doc about a feature. One reason for this is that basic users have explanations and upsell information in the UI, so this will mostly be self-evident.
    • 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 (that is, 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 User management concepts.

Document requirements for relevant role or capability

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

  • Note that when creating a doc about a new feature, we don't document requirements related to user type or group.
  • Note that our standard roles are just aggregations of capabilities. This means that there can be multiple standard roles that have some of 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-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-user-models): the [**Billing user** role](com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts#standard-roles).

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

問題を作成する
Copyright © 2022 New Relic Inc.