Writing instructions

Instructions are the student-facing guidance for each step. They describe what the student needs to accomplish — not how to do it.

What vs. how

GenLabZ supports multiple interfaces and runtimes. A student might complete a step using the AWS Console, the CLI, or an SDK. Instructions should work for all of them, which means they can’t prescribe specific click paths, commands, or parameter values.

Include in instructions:

• What resource to create and its key characteristics
• What configuration is required, described in terms of purpose rather than specific values
• References to prior outputs by handle name when the step depends on them
• The relationship between this resource and others in the project

Leave out of instructions:

• Console navigation paths (“In the AWS Console, click Services > Lambda”)
• CLI commands (“Run: aws lambda create-function ...”)
• Specific parameter values (“Set the timeout to 30 seconds”, “Use us-east-1”)
• SDK code snippets or pseudocode

Examples

Good	Bad
”Create a Lambda function with the Python 3.12 runtime and an execution role that allows writing to DynamoDB"	"In the AWS Console, navigate to Lambda and click Create function"
"Configure the function’s environment variables to include the table name from the prior step"	"Run: aws lambda create-function --function-name my-api-fn --runtime python3.12"
"Create an API Gateway HTTP API and integrate it with the Lambda function from the previous step"	"Set the memory to 256MB and timeout to 30 seconds”

Worked example

Building on the VPC example from Objectives and steps:

steps:
  - id: "01"
    title: Create VPC
    instructions:
      - Create a VPC with CIDR block 10.0.0.0/16
      - Enable DNS hostnames and DNS resolution
    outputs:
      - name: 01_01_vpc_id
        type: AWS::EC2::VPC
        description: The VPC that will contain all project resources

  - id: "02"
    title: Create and attach Internet Gateway
    instructions:
      - Create an Internet Gateway
      - Attach the Internet Gateway to the VPC
    inputs:
      - 01_01_vpc_id
    outputs:
      - name: 01_02_igw_id
        type: AWS::EC2::InternetGateway
        description: Internet Gateway for public subnet internet access

  - id: "03"
    title: Configure public routing
    instructions:
      - Create a Route Table in the VPC
      - Add a route for 0.0.0.0/0 targeting the Internet Gateway
    inputs:
      - 01_01_vpc_id
      - 01_02_igw_id
    outputs:
      - name: 01_03_public_rt
        type: AWS::EC2::RouteTable
        description: Route table for public subnets

Notice that the instructions describe the outcome (“Create a VPC with CIDR block 10.0.0.0/16”) rather than the procedure. The student decides whether to use the console, CLI, or SDK.

When instructions reference prior steps

When a step depends on a resource from a previous step, the instruction should name the resource by its role in the project, not by its handle name. The handle is for the platform; the instruction is for the student.

Good: “Attach the Internet Gateway to the VPC” Not needed: “Attach 01_02_igw_id to 01_01_vpc_id”

The student doesn’t see handle names — they see the resources they’ve created. Keep instructions in human terms.

Keeping instructions stable

Instructions are written after objectives and steps are approved. If you change a step’s scope later, review its instructions to make sure they still reflect what the step is actually doing. Instructions that describe a different action than the step title are a common source of confusion during testing.