This doc explains required styles and recommended phrasings for user roles/permissions-related documentation.
Note about user models
This style guide mostly applies to writing about users on our newer user model, not our 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 our newer 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. 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. |
Example use: This capability is included with the All product admin role. | Preferred for docs: sentence case, 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. When referencing roles, we recommend linking to the standard roles doc section. | |
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 it can be important to format these to indicate that we're referencing terms with specific New Relic meaning. When referencing the default groups, we recommend linking to the explanation of default groups. | |
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"), 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. |
Guidelines for documenting user permissions/roles
There are two main factors affecting a New Relic user's ability to access a New Relic feature:
- User type: we almostly entirely constrain information about user type to the user type doc.
- Roles and capabilities: we almost entirely constrain information about this to the dedicated user management docs:
In other words, we do not place information about user type and roles/capabilities in product-feature-related docs, with the following exceptions:
- For user type: for most product features, it's obvious to a user if something is off-limits due to user type (for example, they see a UI message about user type). If it's not obvious that something is off limits due to user type, you may document that in a feature doc's requirements section. For example, it won't be immediately obvious to a user of NerdGraph why they can't make certain requests, so that is a situation where we'd document user type in the primary NerdGraph doc.
- For roles and permissions: if there's a specific reason to include user type or roles/permissions in a feature doc's requirement section, you may include it. For example: if a permission that controls access to a feature isn't obvious from the name of the permissions (like service levels management permissions), we should document it.
- For organization and user management permissions, we document the roles required. This is because there are not that many of these, and also because the permissions governing these are not exposed in the roles and permissions UI and thus are less obvious to customers.
Considerations for documenting both original and new user model
If you need to include requirements about newer user model roles or permissions, you'll probably need to also include details about the original user model (assuming that feature is available for that audience). 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 [our newer user model](/docs/accounts/original-accounts-billing/original-product-based-pricing/overview-user-models): the [**Billing** administration setting](/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts#admin-settings).