Add FAQ section to docs (#314)

* Fix titles to kill warnings

* New FAQ docs section

* Tweak wording, mention alternative log enabling strategy

Author: sgarcez

docs/cloudformation_compatibility.rst

@@ -1,5 +1,5 @@
 CloudFormation Compatibility Section
-===============
+====================================
 
 .. contents::
 
@@ -30,7 +30,7 @@ DependsOn Attribute:
     ...
 
 CloudFormation Intrinsic Funtions
--------------------
+---------------------------------
 Currently, we do not support all Intrinsic Functions for all Property Values in `AWS::Serverless::*` resources but is fully available in other CloudFormation resources. Please see below tables for a details on which Intrinsic Functions can be used on a given field.
 
 The Condition Function is not currently supported on any ``AWS::Serverless::*`` Resource type

docs/faq.rst

@@ -0,0 +1,45 @@
+
+FAQ
+===
+
+Frequently Asked Questions
+
+.. contents::
+  :local:
+
+How to manage multiple environments?
+------------------------------------
+
+  *Terminology clarification: Environment and Stage can normally be used interchangeably but since AWS API Gateway relies on a concrete concept of Stages we'll use the term Environment here to avoid confusion.*
+
+**We recommend a one-to-one mapping of environment to Cloudformation Stack.**
+
+This means having a separate CloudFormation stack per environment, using a single template file with a dynamically set target stack via the ``--stack-name`` parameter in the ``aws cloudformation deploy`` command.
+
+For example, lets say we have 3 environments (dev, test, and prod).
+Each of those would have their own CloudFormation stack — `dev-stack`, `test-stack`, `prod-stack`. Our CI/CD system will deploy to `dev-stack`, `test-stack`, and then `prod-stack` but will be pushing one template through all of these stacks.
+
+This approach limits the 'blast radius' for any given deployment since all resources for each environment are scoped to a different CloudFormation Stack, so we will never be editing production resources on accident.
+
+If we need to bring up separate stacks for different reasons (multiple region deployments, developer/branch stacks) it will be straightforward to do so with this approach since the same template can be used to bring up and manage a new stack independent of any others.
+
+In cases where you need to manage different stages differently this can be done through a combination of Stack Parameters, Conditions, and Fn::If statements.
+
+How to enable API Gateway Logs
+------------------------------
+
+Work is underway to make this functionality part of the SAM specification. Until then a suggested workaround is to use the ``aws cli update-stage`` command to enable it.
+
+.. code-block:: console
+
+    aws apigateway update-stage \
+      --rest-api-id <api-id> \
+      --stage-name <stage-name> \
+      --patch-operations \
+        op=replace,path=/*/*/logging/dataTrace,value=true \
+        op=replace,path=/*/*/logging/loglevel,value=Info \
+        op=replace,path=/*/*/metrics/enabled,value=true
+
+The command above can be run as a post deployment CI step or it could be triggered by a `custom resource <https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html/>`_ within the same CloudFormation template.
+
+Please note that in either case you will see metric gaps between the time CloudFormation updates API Gateway and the time this command runs.

docs/index.rst

@@ -13,6 +13,7 @@ What's New?
 - ``Globals`` section 
 - Support for Traffic Shifting Lambda deployments 
 - Refer to resources automatically created by SAM 
+- ``FAQ`` section 
 
 .. toctree::
     :hidden:
@@ -22,3 +23,4 @@ What's New?
     safe_lambda_deployments.rst
     policy_templates.rst
     internals/index
+    faq.rst