|
1 | | -# AWS Developer Tutorials - Instructions |
| 1 | +# Instructions |
2 | 2 |
|
3 | | -This directory contains instructions and resources for generating new AWS CLI tutorials and scripts. |
| 3 | +You can use the instructions in this folder to generate new scripts and tutorials for the AWS CLI based on existing content. The instructions use existing AWS Documentation and CLI examples to generate working scripts for the AWS CLI, even if there isn't a specific example for your use case. |
4 | 4 |
|
5 | | -## Overview |
| 5 | +Choose a use case or scenario for one or more services. Find an existing documentation topic for the use case. The content doesn't need to reference the AWS CLI directly, but it helps if you have CLI examples in the AWS CLI GitHub repository. |
6 | 6 |
|
7 | | -The instructions in this directory guide you through the process of creating high-quality AWS CLI tutorials and scripts using Amazon Q Developer CLI. These instructions are designed to help you: |
| 7 | +## Prerequisites |
8 | 8 |
|
9 | | -1. Collect information about AWS services and use cases |
10 | | -2. Generate working AWS CLI scripts |
11 | | -3. Create comprehensive tutorials that explain the scripts |
12 | | -4. Validate and improve both scripts and tutorials |
| 9 | +To generate tutorials, you need the following tools. |
13 | 10 |
|
14 | | -## Directory Structure |
| 11 | +- The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) |
| 12 | +- The [Q CLI](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html) |
| 13 | +- The [AWS Docs MCP server](https://awslabs.github.io/mcp/servers/aws-documentation-mcp-server/) |
| 14 | +- The [AWS CLI GitHub repository](https://github.com/aws/aws-cli/tree/develop/awscli) |
15 | 15 |
|
16 | | -- `/tutorial-gen`: Step-by-step instructions for generating tutorials and scripts |
| 16 | +The AWS CLI repo has examples for AWS CLI commands. The instructions direct Q to find these in the repo in your user directory. If you clone the repo somewhere else, indicate this in the prompt. |
17 | 17 |
|
18 | | -## Tutorial Generation Process |
| 18 | +## Create a folder |
19 | 19 |
|
20 | | -The tutorial generation process is divided into several steps, each with its own instruction file in the `/tutorial-gen` directory: |
| 20 | +Create a new folder in the [tuts](../tuts) directory for your use case, following the naming convention. |
21 | 21 |
|
22 | | -1. **Information Collection** |
23 | | - - Collect documentation topics |
24 | | - - Gather example CLI commands |
| 22 | + ``` |
| 23 | + 001-lightsail-gs |
| 24 | + 002-vpc-gs |
| 25 | + ``` |
25 | 26 |
|
26 | | -2. **Script Creation** |
27 | | - - Generate an initial script |
28 | | - - Test and run the script |
29 | | - - Validate script functionality |
30 | | - - Simplify and improve the script |
| 27 | +Use the next available number after the highest number in use. Indicate the service name or names and the use case in the folder name. You can use `gs` for getting started use cases. |
31 | 28 |
|
32 | | -3. **Tutorial Creation** |
33 | | - - Draft a tutorial based on the script |
34 | | - - Validate tutorial content |
| 29 | +## Prompt |
35 | 30 |
|
36 | | -4. **Finalization** |
37 | | - - Address feedback |
38 | | - - Make final improvements |
| 31 | +Open Q chat in the new folder. Pass the URL to an existing topic with some additional instructions |
39 | 32 |
|
40 | | -## Using These Instructions |
| 33 | +> read the instructions in the ../../instra/tutorial-gen folder and follow them in order, using this topic: https://docs.aws.amazon.com/payment-cryptography/latest/userguide/getting-started.html when instructed to run the script in step 2b, it's ok to actually run the script and create resources. this is part of the process. when you generate the script, be careful to check required options and option names for each command." |
41 | 34 |
|
42 | | -To generate a new tutorial: |
| 35 | +Q tends to not run the script unless you specify this in the prompt. Q processes the instructions in order to generate a script, test it, simplify it, and generate and revise a tutorial. The process can take 20-40 minutes depending on the available documentation and examples. |
43 | 36 |
|
44 | | -1. Start with the file `0-general-instructions.md` in the `/tutorial-gen` directory |
45 | | -2. Follow the numbered instruction files in sequence |
46 | | -3. Use Amazon Q Developer CLI to assist with each step |
47 | | -4. Place the final tutorial and script in a new folder in the `/tuts` directory |
| 37 | +## Pull requests |
48 | 38 |
|
49 | | -## Example Usage with Amazon Q Developer CLI |
| 39 | +The tool generates a lot of artifacts including intermediate script revisions that generate errors. Submit a pull request with only the final revision of the script and tutorial. Rename these after the use case follow this convention. |
| 40 | +torial. Rename these after the use case follow this convention. |
50 | 41 |
|
51 | | -```bash |
52 | | -q "read the instructions in the ../../instra/tutorial-gen folder and follow them in order, using this topic: https://docs.aws.amazon.com/payment-cryptography/latest/userguide/getting-started.html when instructed to run the script in step 2b, it's ok to actually run the script and create resources. this is part of the process. when you generate the script, be careful to check required options and option names for each command." |
| 42 | +``` |
| 43 | +├── 001-lightsail-gs |
| 44 | +│ ├── README.md |
| 45 | +│ ├── lightsail-gs.md |
| 46 | +│ └── lightsail-gs.sh |
53 | 47 | ``` |
54 | 48 |
|
55 | | -This command instructs Amazon Q Developer CLI to: |
56 | | -1. Read the tutorial generation instructions |
57 | | -2. Follow them in order |
58 | | -3. Use the AWS Payment Cryptography getting started guide as the source material |
59 | | -4. Generate and test a script for this service |
60 | | - |
61 | | -## Contributing |
| 49 | +## Testing |
62 | 50 |
|
63 | | -If you have suggestions for improving the tutorial generation process, please submit them as pull requests or issues in the repository. |
| 51 | +All new scripts and tutorials need to be tested by the author. Attach a log from a successful test run to the pull request. |
0 commit comments