Each Quick Start includes an architecture diagram, which illustrates the reference architecture, and a deployment guide, which describes the architecture in detail and provides step-by-step deployment and customization instructions. The deployment guide and architecture diagram are key components of the Quick Start. If you’re building a Quick Start, please review the examples and use the templates in this section to create this content. The Quick Start team will work with you on content reviews and edits, and will publish the finished diagram and deployment guide on the AWS website.

Creating an architecture diagram

Architecture diagram template: PowerPoint

(If you’re updating an existing diagram and don’t have time to redraw it, you can find the older icons archived on the AWS simple icons webpage.)

The architecture diagram gives users a view of the reference architecture built by your Quick Start. At a glance, the user can see the components built by the Quick Start, including the network infrastructure, the AWS services, and your workload instances. The diagram also illustrates the best practices automated by the Quick Start, including scalability, high availability, and security.

If your architecture has many components, consider creating a high-level diagram as well as detailed diagrams that drill down into relevant areas of the architecture. Or, your Quick Start might offer multiple deployment scenarios. In that case, provide a separate diagram for each scenario.

When creating your diagram, follow these guidelines:

  • For services, make sure to use the official AWS icons and labels provided on the AWS simple icons page.
  • Add callouts or labels as necessary to identify workloads, tiers, and other graphics on your diagram.
  • For service names, use the labels provided with the AWS icons. For all other labels and callouts, use sentence case (that is, capitalize the first word only) except for proper nouns.
  • Use background shading with muted colors (included in the templates) to separate tiers or distinct areas of the diagrams, but don’t go overboard with color.
  • Make sure your diagram is clear and legible when imported into the deployment guide.

About deployment guides

Quick Start deployment guides provide detailed information about the architecture of your workload on AWS, including step-by-step instructions for deploying the Quick Start and configuring the template parameters. Deployment guides also outline additional information about usage scenarios, licensing, troubleshooting, and best practices for using your product on AWS.

To help you get started, the AWS team provides an AsciiDoc template that you can use to fill in the details of your deployment. Boilerplate text that is common across all deployment guides is already included in the template.

When planning the level of detail and scope of your deployment guide, use these two examples as a guide:

Users of your Quick Start can access your deployment guide via the GitHub Pages published link. Note that the link to the deployment guide is not available until the AsciiDoc and images files are pushed and merged to the main GitHub branch.

Creating and editing deployment guides

To help you get started, the AWS Quick Start team has provided the base AsciiDoc files with suggested sections and helpful comments in your GitHub repo. Include as much information as necessary to help users understand the usage scenarios for deploying your product on AWS, customization options, and how to get started using the software after deployment.

Here is an example of a published deployment guide with only the boilerplate information included: https://aws-quickstart.github.io/quickstart-documentation-example/. You will add your content to supplement the boilerplate text.

Note: Deployment guides must not contain links to external (Partner-owned) Amazon S3 buckets. Partner-owned content must be hosted elsewhere.

To edit your deployment guide:

  1. Fork the Quick Start repo.
  2. Create a new branch for your documentation edits.
  3. Under the “docs\partner_editable” folder, edit the AsciiDoc files with your content, using an editor of your choice (for example, Visual Studio Code). For details about using AsciiDoc, see the AsciiDoctor website at https://asciidoctor.org/docs/.
  4. Add your architecture diagram and any other images that you want to include to the docs/images folder.

  5. If you wish to generate a preview of your deployment guide, run following commands from the root of your project:

    git submodule update --init --remote

    Depending upon whether you want to preview a development version or the production version of the deployment guide, run either of the following commands:

    Internal version (with file names and editing guidance):

    asciidoctor --base-dir docs/ --backend=html5 -o ../docs/index.html -w --doctype=book -a toc2 docs/boilerplate/index.adoc

    Production version (as seen by end users):

    asciidoctor --base-dir docs/ --backend=html5 -o ../docs/index.html -w --doctype=book -a toc2 -a production_build docs/boilerplate/index.adoc

  6. Once your changes are complete, submit a pull request (PR) to the Quick Start repo’s doc-edits branch.

    The PR is then reviewed by the Quick Start team and either returned for additional information or merged into the main branch. Note that it may take 30 minutes or more for the published deployment guide page to update with the changes.

Using the Second Language feature of the deployment guide:

Note: Change (langCode) to the language code you are using. (ex. docs-cn)
  1. After following steps #1 & 2 from above in “To edit your deployment guide”.
  2. Under the “docs\language\docs-(langCode)\partner_editable” edit the AsciiDoc files with your English language content, using an editor of your choice (for example, Visual Studio Code). For details about using AsciiDoc, see the AsciiDoctor website at https://asciidoctor.org/docs/.
  3. Under the “docs\language\docs-(langCode)\partner_editable” translate files into needed language.

  4. Under the “docs\language\docs-(langCode)\translate-only” translate files into needed language. Do Not Translate the file named “planning_deployment.adoc”

    Warning: For Steps #3 & 4: DO NOT Translate any of the actual markdown language references or any parameters that are being used. As this will break the automation.

  5. If you wish to generate a preview of your deployment guide, run either of the following commands from the root of your project:

    Internal version (with file names and editing guidance):

    asciidoctor --base-dir docs/languages/docs-<langCode> --backend=html5 -o ../../index-<langCode>.html -w --doctype=book -a toc2 docs/languages/docs-<langCode>/index.adoc

    Production version (as seen by end users):

    asciidoctor --base-dir docs/languages/docs-<langCode> --backend=html5 -o ../../index-<langCode>.html -w --doctype=book -a toc2 -a production_build docs/languages/docs-<langCode>/index.adoc

  6. Once your changes are complete, submit a pull request (PR) to the Quick Start repo’s doc-edits branch.

    The PR is then reviewed by the Quick Start team and either returned for additional information or merged into the main branch. You will call the second language site by using the link to the English version and adding “index-(langCode).html” to the end of it. Note that it may take 30 minutes or more for the published deployment guide page to update with the changes.

Updating deployment guides after launch

If you need to make additional updates after your Quick Start is launched, use the same procedure as above. The Quick Start team will review your updates and either request more information or merge the updates into the repo’s main branch.