Merge pull request #1 from lftraining/feature/howtos

Feature/howtos

Author: jdavv

docs/HOWTOs/add-instructions-to-a-lab.md

@@ -0,0 +1,66 @@
+# HOW TO Add Instructions to a Lab
+
+This guide explains how to add instructions to your lab after creating the compute environment.
+
+## Prerequisites
+
+Before you begin, ensure you:
+
+- Have access to the `lftraining` GitHub Organization
+- Are a member of the `lab-authors` team
+- Have created a compute environment using [this HOW TO ](create-a-compute-environment-using-templates.md)
+
+
+## Adding Instructions Using GitHub Web Interface
+
+  ![Writing Instructions](../img/writing-instructions.gif)
+
+1. Navigate to your Pull Request created by the workflow
+2. Click the feature branch `feature/implement-<your-compute-environment>`
+2. Locate the `compute-environments/available/<your-compute-environment>` directory
+3. Find `instructions.en.md` in this directory
+4. Click the edit button (pencil icon) to modify the file
+
+### Writing Instructions
+
+The file uses standard Markdown syntax. When rendered in the lab UI:
+
+- Code blocks get syntax highlighting
+- A copy button appears next to code blocks for easy copying
+
+### Saving Your Changes
+
+After editing the instructions:
+
+1. Click the `Commit changes...` button
+2. Add a meaningful commit message (e.g., "feat: add lab instructions")
+3. Click "Sign off and commit changes"
+
+
+!!!note "Working Locally"
+    If you prefer to work locally, you can clone the repository and edit the files in your preferred editor.
+
+### Automated Environment Creation
+
+After committing your changes:
+
+1. Return to your Pull Request in GitHub
+2. Look for a new comment containing the staging environment URL
+3. Use this URL to preview and test your lab instructions in the actual lab as a student would
+
+  ![Automated Environment Creation](../img/automated-environment-creation.gif)
+
+!!!tip "Testing Your Lab"
+    The staging environment is a complete copy of your lab, allowing you to verify that:
+
+    - Instructions render correctly
+    - Code blocks work as expected
+    - The environment matches your requirements
+
+
+!!!tip "Skipping Environment Creation"
+    Add `[skip ci]` to your commit message body to skip environment creation. This is useful when:
+
+    - Making minor text corrections
+    - Fixing typos
+    - Making multiple small changes before testing

docs/HOWTOs/create-a-compute-environment-using-templates.md

@@ -0,0 +1,89 @@
+# HOW TO Create a new Lab Compute Environment
+
+This guide explains how to create a new compute environment using our automated GitHub workflow.
+
+## Prerequisites
+
+Before you begin, ensure you:
+
+- Have access to the `lftraining` GitHub Organization
+- You are a member of the `lab-authors` team
+
+## Creating a New Compute Environment
+1. Open the lab repository in your browser
+2. Navigate to the Actions tab in the repository
+3. Locate and select the `New Compute Environment` workflow
+4. Click `Run workflow` and fill in the following parameters:
+
+  ![Repository Actions](../img/create-lab-compute-environment.gif)
+
+
+### Workflow Parameters
+
+- **Environment Template** (required)
+  Choose one of the following templates:
+
+  - `k8s-single-node`: Single node Kubernetes environment
+  - `k8s-multi-node`: Multi-node Kubernetes environment
+  - `linux-single`: Single Linux host environment
+  - `linux-dual`: Dual Linux host environment
+
+- **Compute Environment** (required)
+  - Enter the prefix for your compute environment (e.g., "LFS25800")
+
+- **Use Workstation** (required)
+  - Choose whether to include a workstation VM for the student
+  - Defaults to `true`
+
+### Template Configurations
+
+Each template creates different VM configurations:
+
+#### k8s-single-node
+- 1 control plane node
+- Optional workstation
+
+#### k8s-multi-node
+- 1 control plane node
+- 1 worker node
+- Optional workstation
+
+#### linux-single
+- 1 Linux host
+- Optional workstation
+
+#### linux-dual
+- 2 Linux hosts
+- Optional workstation
+
+## What Happens Next
+
+After triggering the workflow:
+
+1. A new feature branch is created (`feature/implement-<compute-environment>`)
+2. The necessary template files are generated based on your selection
+3. A draft pull request is automatically created
+4. You can then customize the environment further by working on the created branch
+
+!!!note "Next Steps"
+    After the workflow completes, review the generated pull request and make any necessary customizations to the environment configuration.
+
+### Finding Your Pull Request
+
+1. Navigate to the Pull Requests tab in the repository
+2. Look for a PR titled `Implement <your-compute-environment>`
+3. Open the PR to review the generated files
+
+  ![Finding your PR](../img/finding-your-pr.gif)
+
+### Working on the Environment Locally
+
+1. Navigate to your local repository
+2. In the PR, click the `Code` dropdown button
+3. Copy the command under "Checkout with GitHub CLI"
+4. Paste and run the command in your terminal:
+   ```bash
+   gh pr checkout <PR-NUMBER>
+   ```
+
+  ![Working locally](../img/working-locally.gif)

docs/img/.gitattributes

@@ -0,0 +1,2 @@
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text