make "Supported AWS Regions" section generic by default

aws-quickstart / quickstart-documentation-base-common

Common components of the quickstart-documentation-base repo. Stored here to facilicate a centralized source-of-truth for common components of our documentation

Apache License 2.0

14 stars 17 forks source link

make "Supported AWS Regions" section generic by default #162

Closed jaymccon closed 3 years ago

jaymccon commented 3 years ago

proposed implementation to make Supported AWS Regions text use a generic blurb instead of per-quickstart content that is likely to go out of date when new regions are released and services add support for regions.

Provides a way to revert back to custom text for partners that require specific statements about supported regions.

Implementation is not finalized and up for discussion. I chose the approach of a variable in _settings.adoc as it will allow us to change the behavior of all quick starts without having to make per-repo commits, and it allows those that wish to stick with the old regions behavior a simple way to do that.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

jaymccon commented 3 years ago

@MarciaRieferJohnston @DelfinGala opened this as a work-in-progress, so you can have a look at my proposed approach prior to our discussion.

MarciaRieferJohnston commented 3 years ago

@jaymccon You mention that adding a variable in _settings.adoc "will allow us to change the behavior of all quick starts without having to make per-repo commits." Let's discuss how that would work. Seems like published docs would still retain their static Region lists and would require per-repo commits.

jaymccon commented 3 years ago

@jaymccon You mention that adding a variable in _settings.adoc "will allow us to change the behavior of all quick starts without having to make per-repo commits." Let's discuss how that would work. Seems like published docs would still retain their static Region lists and would require per-repo commits.

The file will still be present in repo's, but will not be rendered as the file is only rendered if custom_supported_regions is added to settings.adoc and we will not make per repo changes to add it (so any repo wanting the custom text will need to add it). Does that make sense ?

MarciaRieferJohnston commented 3 years ago

@jaymccon Aha. I see. No per-repo commit is needed this way. Elegant. Still, we would need to update the boilerplate submodule per-repo. And for each guide, we would want a human to verify that there were no unforeseen consequences, especially for older guides, given the accumulation of changes in the boilerplate. Maybe we declare this a change from today forward rather than try to update all existing guides?

MarciaRieferJohnston commented 3 years ago

I propose that we add the deploy files (with the deployment steps) to this PR. Their cross references to the "Supported AWS Regions" section need to be tweaked since we no longer list Regions.

jaymccon commented 3 years ago

@MarciaRieferJohnston I'm not against that, just a few callouts:

the deploy* files are in the .specifc/ folder, so will need to be manually updated in each quick start.
the xref (link:#_supported_aws_regions[Supported AWS Regions] will be valid with both generic and custom text, it just doesn;t explicitly tell you what regions you can select with generic. I still think the link is useful, so you can see what error to look out for if you launch in an unsupported region.