Content Guidelines

We use alert banners to communicate system status, warnings, errors, and other important information. They must be clear, concise, and actionable so users can understand the situation and take the right next steps.

We follow these basic rules while writing content for alert banners:

• Voice: Be insightful and clear; do not use heavy jargon.

• Tone: Be helpful and do not blame the user.

• Language: US English

• Voice Structure: Active voice

• Casing: Sentence case and keep proper nouns as is; links in sentence case.

• Punctuation: Use no period for short sentences or sentence fragments. Use full punctuation only when the message is a complete sentence. Do not use exclamation (!) and ellipsis (…).

• Words and phrases to avoid: Please, successfully, oops, sorry, uh-oh, something went wrong, you shall, you can.

Structure of an effective alert message

We use alert banners for 4 levels of severity- info, success, warning, and critical.

An alert message should communicate one or more of the following:

• What happened: Clearly state what triggered the alert or why the user is seeing it.

• Why or how it happened: Briefly explain the cause, when this information is known or helpful.

• What the user can do next: Indicate whether any action is required and clearly state the steps they should take.

• Any alternate solution: Provide a workaround or next-best step if an immediate solution is not available.

Examples:

The info message in this example specifies what happened + what the user can do next.

"To ensure security, the system has generated an FNS policy based on the NSX migration rules. You may modify the secure entities; however, doing so can result in the policy being re-created as one or more separate policies, which may impact the overall security posture."

The warning message in this example specifies what happened + what the user can do next.

"There is a maximum rule limitation in FNS. Split the NSX policies into multiple FNS policies for migration."

The success message in this example specifies what happened.

"All 15 NSX policies applied to the selected VMs are migrated, and the equivalent FNS policies exist."

The critical message in this example specifies what happened + why it happened + what the user can do next.

"Unable to migrate 6 NSX policies attached to the selected VMs. These policies require FNS equivalents to preserve security configuration during migration. Create the corresponding policies manually in FNS before continuing with VM migration."