The policy description provides details of a policy. It's defined in the desc field in each yaml files and will be used to generate policy doc site chromeenterprise.google/policies/, ADM/AMDX templates or some other 3rd party management tools UI.
In general, the policy descriptions should follow the structure below.
<Overview of the policy> <Background> <One or more bullet points for setup> <Any other information>
Using one or two sentences to explain the main function that the policy controls.
It is usually worth a few sentences to describe what the function actually does. Keep in mind that the readers of the policy description are likely not experts in this area.
It’s important to describe different states of a policy, including the unset state. Please also mention whether users can control any setting when the policy is unset or set to a specific value.
Boolean policies usually have 3 states: Enabled, Disabled and not set.
Setting the policy to Enabled, ... Setting the policy to Disabled, ... Not setting the policy, ...
Please use Enabled with capital E and Disabled with capital D.
In some cases, if the policy is default to Enabled or Disabled, combine the not set one to it.
Setting the policy to Enabled or not set, ... Setting the policy to Disabled, ..
If you need a long sentence to describe the policy state or need to repeat yourself in each state, consider putting that information in the background section above and keep the sentences here short.
Similar to boolean, all enum options need to be listed separately. When referring to enum options, please mention their values and captions.
Setting the policy to <0 - caption of option 0>, ... Setting the policy to <1 - caption of option 1>, ... ... Not setting the policy, ...
Same as boolean, if you need a long sentence to describe the policy state or need to repeat yourself in each state, consider putting that information in the background section above and keep the sentences here short.
Those policies are usually complicated. In general, please describe the input requirements, like what each key of the dictionary means or what kind of string format can be accepted.
Any other useful information can be provided here. Here are some common topics.
Uncommon behavior. For example, most policies override user settings by default. If a policy configuration won’t do so, it definitely needs to be highlighted.
When a policy can have a conflict with other policies or contains two mutual options, it’s always a good idea to talk about those edge cases. For example, if there is an allow list and block list, what if an option is put into both lists?
Some policies are planned to be only available for a certain amount of time. It’s very important to communicate it ahead of time. However, it’s ok not to mention a specific date if the timeline is not decided yet.
Same as expiration, a policy can be added before the feature is launched. Please describe the default behavior now and once the feature is rolled out.
Malware could abuse policies to control users' devices. Some policies are particularly dangerous so there will be additional management requirements before applying them. For those policies, please append the following statements at the end of the policy description according to their supported platforms.
On <ph name="MS_WIN_NAME">Microsoft® Windows®</ph>, this policy is only available on instances that are joined to a <ph name="MS_AD_NAME">Microsoft® Active Directory®</ph> domain, joined to <ph name="MS_AAD_NAME">Microsoft® Azure® Active Directory®</ph> or enrolled in <ph name="CHROME_BROWSER_CLOUD_MANAGEMENT_NAME">Chrome Browser Cloud Management</ph>`. On <ph name="MAC_OS_NAME">macOS</ph>, this policy is only available on instances that are managed via MDM, joined to a domain via MCX or enrolled in <ph name="CHROME_BROWSER_CLOUD_MANAGEMENT_NAME">Chrome Browser Cloud Management</ph>.
The policy description can’t be longer than 3500 characters. However, even before that limit is reached, as long as it’s necessary, consider creating a webpage for additional details and link it from the policy description.
Usually, this can be a help center article. Please contact a tech writer to create one for you. It can also be any public documentation that can help. For example, if the policy accepts urls as input, you can link this or this article to avoid repeating most edge cases of URL input and only focus on the unique part.
Note that when linking the help center article, please use a p link (e.g. a?p=url_blocklist_filter_format) instead of a number link (e.g. a/answer/9942583). Contact a tech writer to create the p link for you.
The Policy description will be displayed in various different tools. Some of these tools may not support any kind of formatting except splitting each paragraph with an empty line.
Line A Line B Line C
Note that single line return may be used to keep the line length reasonably short. But it will be ignored in some generated documentations. In other words,
Line A Line B Line C
Will be presented as
Line A Line B Line C
If complicated formatting is needed, please create a help center article to include better expression such as graphs and tables.
All policy descriptions and captions will be translated into multiple languages. Avoid using phrases that are unique to English culture and hard to translate.
In addition to that, to ensure consistency in the policy descriptions, the following is a mapping of how various product names and the like should be referenced. All placeholders tags must be opened and closed on the same line to avoid validation errors.
<ph name="PRODUCT_NAME">$1<ex>Google Chrome</ex></ph><ph name="PRODUCT_OS_NAME">$2<ex>Google ChromeOS</ex></ph><ph name="PRODUCT_OS_FLEX_NAME">Google ChromeOS Flex</ph><ph name="CHROME_BROWSER_CLOUD_MANAGEMENT_NAME">Chrome Browser Cloud Management</ph><ph name="CHROME_CLEANUP_NAME">Chrome Cleanup</ph><ph name="CHROME_REMOTE_DESKTOP_PRODUCT_NAME">Chrome Remote Desktop</ph><ph name="CHROME_SYNC_NAME">Chrome Sync</ph><ph name="GOOGLE_ADMIN_CONSOLE_PRODUCT_NAME">Google Admin console</ph><ph name="GOOGLE_CALENDAR_NAME">Google Calendar</ph><ph name="PRODUCT_NAME">Google Cast</ph><ph name="GOOGLE_CLASSROOM_NAME">Google Classroom</ph><ph name="CLOUD_PRINT_NAME">Google Cloud Print</ph><ph name="GOOGLE_DRIVE_NAME">Google Drive</ph><ph name="GOOGLE_PHOTOS_PRODUCT_NAME">Google Photos</ph><ph name="GOOGLE_TASKS_NAME">Google Tasks</ph><ph name="GOOGLE_UPDATE_NAME">Google Update</ph><ph name="GOOGLE_WORKSPACE_PRODUCT_NAME">Google Workspace</ph><ph name="ANDROID_NAME">Android</ph><ph name="FUCHSIA_OS_NAME">Fuchsia</ph><ph name="IOS_NAME">iOS</ph><ph name="LINUX_OS_NAME">Linux</ph><ph name="MAC_OS_NAME">macOS</ph><ph name="MS_WIN_NAME">Microsoft® Windows®</ph><ph name="IE_PRODUCT_NAME">Internet® Explorer®</ph><ph name="MS_AD_NAME">Microsoft® Active Directory®</ph><ph name="MS_AAD_NAME">Microsoft® Azure® Active Directory®</ph>Using placeholders means the text won’t be translated. Please update the list above if a new placeholder is introduced.