To remove some of the guesswork involved in crafting parameter names and labels, and to ensure consistency, we’ve developed the guidelines described in this section. Following these guidelines will help you provide clear, consistent, self-explanatory prompts and instructions in the AWS CloudFormation console for users who are deploying your Quick Start.

General guidelines

  • Use clear, accurate, easy to understand labels and descriptions. (See the following sections for details.)
  • Check labels and descriptions for typographical errors, and fix them.
  • Use correct branding for AWS services and for your own product references.
  • Use the following standards for group labels, parameter names, and parameter labels where they apply: Standard parameters for Quick Starts

  • When you use the VPC and bastion host templates as building blocks, use the parameter names and labels that are already defined in those templates. Don’t change these.

Naming parameters

For parameter names (logical IDs), follow these guidelines:

  • Use Pascal case, beginning with an uppercase letter.

    keypairname, vpcTenancy

    KeyPairName, VPCTenancy

  • Keep names short but specific.

    Version

    BitBucketVersion

  • It’s OK to abbreviate service names.

    EMRClusterSize

  • It’s OK to abbreviate “Availability Zone.”

    ThirdAZ

  • Identify subnets as public or private.

    Subnet1ID

    PublicSubnet1ID

  • For items that are entities, the parameter number should directly follow the entity name.

    WSFCNode1, WSFCNode2

  • If a feature is attached, extends, or complements the entity, its name should follow the entity name.

    ADServer2PrivateIP, WSFCNode2PrivateIP3

Crafting parameter labels

Labels are friendly names that the AWS CloudFormation console displays instead of the logical IDs. Make sure to add a label) for each parameter, and follow these guidelines:

  • Keep the label short if possible, but make sure it’s descriptive.

    API key that the firewall will use to authenticate API calls

    API key for firewall

  • Use sentence case (capitalize only the first word and proper nouns).

    SAP HANA Instance Type

    SAP HANA instance type

  • Use correct AWS service names, but don’t spell them out.

    Amazon Elastic Block Store volume size

    Amazon EBS volume size

  • Spell out “AZ” (only exceptions are “Multi-AZ” and “Single-AZ”).

    Number of AZs

    Number of Availability Zones

  • Don’t include too much information (such as values, units, examples, optional/required designations) in the label—specify those details in the parameter description. Avoid adding details to parameter labels

    SAP HANA Server host name (e.g., saphanaqs)

    SAP HANA server host name

  • Don’t add punctuation (such as periods or colons) to the end of the label. Don't add punctuation to the end of parameter labels

    CIDR range for your VPC:

    CIDR range for your VPC

  • Don’t phrase the label as a question or instruction. This draws attention away from the important information.
    Don't phrase parameter labels as questions or instructions

    Would you like to turn on automatic recovery?

    Turn on automatic recovery

  • Add spaces between words and numbers.

    Private subnet1 CIDR

    Private subnet 1 CIDR

Crafting parameter descriptions

The parameter description is a string of up to 4000 characters. Add a description for each parameter to provide guidance for using the parameter effectively. Follow these guidelines:

  • Provide useful information, including minimum/maximum values, syntax, requirements, and examples.

    A CIDR block that’s allowed external access to the Remote Desktop gateways. We recommend that you use a constrained CIDR range to reduce the potential of inbound attacks from unknown IP addresses.

  • For Boolean parameters (true/false or yes/no settings), start with “Choose” and explain what happens if they change the default. Describe the effects of the non-default value for Booleans

    Choose Yes to enable server-side encryption in Amazon S3.

    Choose No to disable server-side encryption in Amazon S3.

  • For descriptions of non-Boolean parameters, start with a noun phrase.

    Enter the name of the S3 bucket that stores your backup data.

    The name of the S3 bucket that stores your backup data.

  • Don’t specify the default value in the description. It’s already displayed in the value field. Don't specify the default value

  • Specify both minimum and maximum allowed values. Specify minimum and maximum allowed values

  • Specify the unit if it isn’t obvious. Add it to the description, not to the label. Specify the unit

  • Explain syntax requirements and provide examples in the description, not in the value field. Otherwise, the user might overlook these parameters, and the defaults might break the deployment. Don't use the value field to display syntax

Crafting parameter group labels

AWS CloudFormation parameter groups enable you to display parameters in an intuitive way. For example, you could place all the network-related parameters in a category called Network configuration and your database configuration parameters in a category called Database configuration. For instructions on setting up groups, see the AWS::CloudFormation::Interface resource. To label groups, follow these guidelines:

  • Use sentence case.

  • Keep short but descriptive.

  • Include the word “configuration” (in lowercase).

    Syntax for group labels

  • Don’t include punctuation.

    Don't include punctuation in group labels

Specifying optional parameters

  • For optional parameters, include “(Optional)” at the beginning of the parameter description for best visibility. If you add it to the end of the description or as a sentence (e.g., “This parameter is optional.”) within the description, it won’t stand out as well. Best placement for optional designation

  • Don’t include the optional designation in the parameter label. Don't include optional designation in parameter labels

  • Don’t include the optional designation in the group label, unless all the parameters in that group are optional. If they are, add “(optional)” to the end of the group label. Don't include optional designation in group labels

Ordering parameters and groups

  • Follow an order that makes sense, from general to specific, from simple to advanced.

    Network configuration before workload configuration, VPC parameters before subnet parameters

  • The Quick Start configuration section is always last:

    Network configuration

    Bastion host configuration

    All other groups, in a logical order

    AWS Quick Start configuration