Cleanup Documentation #176
Conversation
|
Good start |
|
A more readable link for the README: https://github.com/unbounce/iidy/blob/cleanup-docs/README.md |
README.md
Outdated
| * It provides immediate, readable feedback about what CloudFormation is doing | ||
| and any errors it encounters. | ||
| * It is simple to learn, understand, and use. | ||
| parts, that map directly to CloudFormation's |
There was a problem hiding this comment.
Some words are missing: "There are fewer moving parts and its commands map directly to CloudFormation's"
README.md
Outdated
| stack. | ||
| * It does some template validation, guards against common issues, and will be | ||
| extended over time to validate our best practices and security policies. | ||
| * It provides seemless integration with AWS Parameter Store |
There was a problem hiding this comment.
We should be consistent with the final period on the items in this list.
README.md
Outdated
| ## Usage | ||
|
|
||
| ### Help | ||
| ``` | ||
|
|
||
| ```shell |
There was a problem hiding this comment.
We should skip the shell here as the syntax highlighting is incorrect in the output.
README.md
Outdated
| @@ -94,98 +93,116 @@ Commands: | |||
| iidy update-stack <argsfile> update a cfn stack based on stack-args.yaml | |||
| iidy create-or-update <argsfile> create or update a cfn stack based on stack-args.yaml | |||
| iidy estimate-cost <argsfile> estimate aws costs based on stack-args.yaml | |||
|
|
|||
| ... | |||
There was a problem hiding this comment.
Historically I've been replacing the ...s here with blank lines.
README.md
Outdated
|
|
||
| Status Codes: | ||
| Success (0) Command successfully completed | ||
| Error (1) An error was encountered while executing command | ||
| Cancelled (130) User responded 'No' to iidy prompt or interrupt (CTRL-C) was received | ||
| ``` | ||
|
|
||
| ### The `argsfile` (aka `stack-args.yaml`) | ||
| ### Environment Variables |
There was a problem hiding this comment.
I think we should discourage people from wrapping iidy in complex shell scripts that use these envvars. For that reason, I'd move this section done.
README.md
Outdated
| # example stack-args.yaml | ||
| #### Importing Data | ||
|
|
||
| Data can be imported into the stack args file using the `$imports` block. |
There was a problem hiding this comment.
$imports: with the colon
| Type: AWS::SNS::Topic | ||
| Properties: | ||
| DisplayName: "Hello {{Bar}}" | ||
| - CLI options (see above) |
There was a problem hiding this comment.
This is a better spot to cover the envvars than above.
| # Converting Existing CloudFormation Stacks to iidy | ||
|
|
||
| Converting current stacks to iidy can be done through the iidy | ||
| convert-stack-to-iidy` command, which accepts two parameters: the stack name of |
There was a problem hiding this comment.
Looks like an opening backtick was missed here.
| stored. For example: | ||
|
|
||
| ```shell | ||
| iidy convert-stack-to-iidy my-cloudformation-stack-1 . |
There was a problem hiding this comment.
For the example, I think we should use a sub-dir.
docs/using-parameter-store.md
Outdated
| @@ -0,0 +1,36 @@ | |||
| ### Using Parameter Store for Secrets | |||
There was a problem hiding this comment.
We should also cover the iidy params commands here.
README.md
Outdated
|
|
||
| Any parameter used by iidy can be set using IIDY_{{argname}} | ||
| ## Additional Documentation |
There was a problem hiding this comment.
I think we should lead with the readme with TOC of all documentation for easy reference.
docs/yaml-preprocessing.md
Outdated
| # - c | ||
| ``` | ||
|
|
||
| * `!$escape` 🤷️ |
There was a problem hiding this comment.
some-entry: !$escape "{{ this is escaped }}"
some-entry: "{{ this is escaped }}"
There was a problem hiding this comment.
entry2: $escape
- $! testing
entry2:
- $! testing
docs/yaml-preprocessing.md
Outdated
| # - c | ||
| ``` | ||
|
|
||
| * `!$escape` 🤷️ |
There was a problem hiding this comment.
I.e. $!escape prevents `iidy from doing any pre-processing on the child tree.
|
I think it would be helpful to provide some examples of the |
| | `git:describe` | Get current git description (via `git describe --dirty --tags`) | `git:describe` | | ||
| | `git:sha` | Get current git sha name (via `git rev-parse HEAD`) | `git:sha` | | ||
| | `random:dashed-name` | Generate a random dashed name, for example: `'uptight-guitar'` | `random:dashed-name` | | ||
| | `random:name` | Generate a random dashed name, for example: `'uptightguitar'` | `random:name` | |
There was a problem hiding this comment.
Description for random:name seems to have been copied from name:dashed-name but not changed.
No description provided.