--- title: "Creating Lab Instructions" slug: "creating-lab-instructions" updated: 2024-09-13T16:30:07Z published: 2024-09-13T16:30:07Z --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.skillable.com/llms.txt > Use this file to discover all available pages before exploring further. # Creating Lab Instructions Skillable labs support fully integrated Lab Instructions that keep learners engaged with the core environment by living side-by-side, removing the need for context switching between tabs or windows, and adding interactivity like one-click actions to send text into or otherwise manipulate virtual machines. When creating instructions for labs in Skillable Studio, there are a number of considerations to make: - [**Basics:**](/v1/docs/creating-lab-instructions#basics) - [Instructions Format](/v1/docs/creating-lab-instructions#instructions-format) - [Instructional Design](/v1/docs/creating-lab-instructions#instructional-design) - [**Skillable Features:**](/v1/docs/creating-lab-instructions#skillable-features) - [Instruction Sets](/v1/docs/creating-lab-instructions#instruction-sets) - [Instruction Source (storage location)](/v1/docs/creating-lab-instructions#instruction-source) - [Custom Syntax](/v1/docs/creating-lab-instructions#custom-syntax) - [Visual Styling](/v1/docs/creating-lab-instructions#visual-styling) ![](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/image(126).png) ## Basics When it comes to authoring instructions, there a number of staples that are important to know regardless of your lab provider. Those are the Instructions Format (how they are being created) and the [Instructional Design](https://education.purdue.edu/2024/01/what-is-instructional-design/) philosophy being utilized. ### Instructions Format An instructions format refers to how they are being created. **Skillable Studio’s** **default and recommended instructions format is Markdown**, where we support [Skillable Custom Syntax](/v1/docs/creating-lab-instructions#custom-syntax) to extend instructions capabilities. Additionally, Skillable Studio supports the following traditional document formats for instructions: - PDF - Word - HTML - XPS > [!WARNING] > Best Practice: Use Markdown format > > Use the Markdown format for the best balance between flexibility and ease to maintain. Markdown also supports the addition of HTML elements if need and is the only Instructions Format capable of interacting with the lab environment. ### Instructional Design Instructional design is the idea of how you create instructions. There are numerous philosophies that may shape the design of your learning content, and it may even vary based on use case or intended audience of individual labs. Examples of a few instructional design philosophies that are prevalent in labs include: - **Traditional step-by-step:** This style of instructional design is typically very granular and specific, telling a learner exactly where to point and click along every step of the way. - **Challenge-centric:** Challenge-centric instructions go the next step in abstraction and are generally more about giving a user a higher-level task to complete while allowing them to discover exactly how on their own. It is common to see hints provided in challenge-centric instructions that help a learner get back on track if they have some difficulty. - Performance-Based Testing**or Exam:**Performance-based testing (PBT) or exam instructions are generally a little more high level than challenge-centric even, and do not provide any hints to the learner. This style is generally used more for a high-stakes exam or capstone to a learning journey. Learn more about [Skillable’s instructions writing best practices](/v1/docs/instructions-writing-best-practices). ## Skillable Features In addition to the basics around creating instructions for a lab experience, Skillable has a number of features to make lab instructions more engaging, tailored to your brand, or better align with your organization’s access or storage requirements. ### Instruction Sets Instruction Sets are a Skillable capability that both increase the re-usability of lab environments, including delivering a single lab in multiple languages. Instruction Sets do not currently work with [external Instruction Sources](/v1/docs/creating-lab-instructions#instruction-source) Learn more about using [Instruction Sets](/v1/docs/instruction-sets). > [!WARNING] > Best Practice: Use Instruction Sets to reach a global audience > > Instruction sets allow you to deliver a lab multiple languages so learners can feel right at home. ### Instruction Source The Instruction Source is where the instructions for a lab are stored. Skillable supports both native storage and external sources for various purposes, as outlined below: ****Expand to compare instruction source options**** | Feature/Capability | Skillable Native Instructions | Instructions Include | GitHub/ADO Integration | Traditional Documents | | --- | --- | --- | --- | --- | | Use Skillable Instructions Editor | ✅ | | | | | Combine with Skillable Native Instructions | ✅ | | | ✅ | | Use Instruction Sets for localization or differentiation | ✅ | ✅ | | | | Support Replacement Tokens for dynamic system values | ✅ | ✅ | ✅ | | | Support activities with real-time feedback during the lab | ✅ | ✅ | ✅ | | | Support activities for skill validation at end of lab | ✅ | ✅ | ✅ | ✅ | | Support Variables for User or API defined values | ✅ | ✅ | ✅ | | | Support replacements for modifying instructions without modifying the source | ✅ | ✅ | ✅ | | | Include one-click lab environment interactions (TypeText, Switch VMs, etc.) | ✅ | ✅ | ✅ | | | Use HTML Syntax for advanced customization | ✅ | ✅ | ✅ | ✅ | | Use Markdown, including custom Skillable syntax | ✅ | ✅ | ✅ | | | Can be maintained & edited outside of Skillable Studio | | ✅ | ✅ | ✅ | | Possibility for robust version control & change management | | ✅ | ✅ | ✅ | | Use public document repositories | | ✅ | ✅ | ✅ | | Use private document repositories | | | ✅ | | #### Skillable Storage By default, labs use Markdown, Skillable Studio’s native storage, and Skillable’s native Instructions Editor. When using this source, capabilities like Replacement Tokens, Activities, Variables, etc. are more discoverable and easier to utilize. If you are using document-based instructions (PDF, Word, HTML), these can be stored in Skillable’s storage as well - but can generally not benefit from features like Replacement Tokens or Variables. They can still be used in combination with Activities. #### External Sources Skillable Studio also supports integrations with external instruction sources such as [GitHub](https://github.com/) and [Azure DevOps (ADO)](https://azure.microsoft.com/en-us/products/devops). These sources also require utilizing Markdown formatting, but provide benefits like git/version control and reuse of content in locations other than Skillable (for example, your own documentation). External instruction sources may be public or private repositories, but do not currently work in combination with [Instruction Sets](/v1/docs/creating-lab-instructions#instruction-sets). Skillable currently supports the following external instruction sources: - [GitHub Repository](/v1/docs/github-repository) - [ADO Private Repository](/v1/docs/ado-private-repository) Skillable also supports URL sourced instructions. URL sourced instructions must be publicly available (not require authentication) and can be document-based (PDF, Word, HTML) with the same functionality as document-based instructions in Skillable storage or it can be an Instructions Include. Includes are a direct link to raw markdown with full functionality of Replacement Tokens, Variables, and Replacements. > [!WARNING] > Best Practice: Use Skillable Studio Storage > > To best harness all of Skillable Studio’s advanced capabilities, it is recommended to use the Instruction Editor in Skillable Studio. Consider using an external instruction source, or combining Skillable storage with Includes if you require: > > - Robust version control & history > - External management of user access > - Share document outside of the context of a lab ### Custom Syntax While Skillable Studio’s default instructions language is Markdown (rooted in [Commonmark Markdown](https://commonmark.org/help/)), we have extended this language to support a myriad of additional options. These tools let your instructions become not only more unique, but more interactive and effective by allowing learners to focus on what’s most important. Some of Skillable’s custom syntax include: - TypeText - Collapsible Sections - Links that modify something in the virtual machine (run a key combo, execute a script, etc.) - Dialog Windows - Dropdowns, Text Input Boxes, and Sections that change based on different values - And many more! Learn more about [Creating Instructions with Markdown Syntax](/v1/docs/creating-instructions-with-markdown-syntax). > [!WARNING] > Best Practice: Make engaging, but not cluttered, instructions > > Adding advanced components can create an engaging experience that has users coming back for more. However, lend caution and avoid adding too many interactive elements in a small area - it can become intimidating and overwhelming for some users. ### Visual Styling At Skillable we understand the importance of a brand identity. Use Themes to make the lab client truly look and feel like one of your own native applications. Skillable Themes support easy customization of colors, fonts, and logo with additional support for CSS and Javascript for advanced uses. Learn more about [Theming Labs (skillable.com)](/v1/docs/theming-labs) > [!WARNING] > Best Practice: Make Skillable Labs look & feel like your own > > Create a seamless user experience by tailoring Skillable Labs to feel like an extension of your own brand. The lab content and instructions written in the Instructions Editor and displayed in the lab user interface. Skillable's lab building & authoring platform. Markdown is an easy-to-use set of markup language to format text. Markdown also supports the use of embedded HTML syntax to format the contents. Performance-based testing is a challenge-centric, scored lab used for skills validation. It uses activities, such as Activity Based Assessments (ABA), that have scoring turned on. Questions and Automated Activities are used to validate a Learners' practical skills through the completion of technical tasks, and the results are generated at the end of a lab. Used to replace text in lab instructions with a defined variable that is unknown at the time of authoring the lab instructions. These variables may not be generated or created until the lab is launched by the student. These can include usernames, user first name, user last name, running lab instance ID number, etc. Activities are configured in the instructions editor and represented in the lab instructions by a replacement token. Activities fall into two broad categories: Questions and Automated. - Questions are multiple choice or short answer questions. - Automated Activities interact with the lab environment (Virtual Machine/Container/Cloud Platform). Variables store information and then that information can be recalled or used in the lab. Variables can be used in Life Cycle Actions, Automated Activities, and in lab instructions. Markdown that is located publicly anywhere on the internet and accessible from a URL without authentication. Most commonly, a public GitHub repository. Replacements enable you to find text that presents in the lab instructions and change how it displays to the user, without changing the underlying instructions. These are commonly used when using External Instruction Sources that serve multiple purposes and need to be adapted for a lab without modifying the source. Themes allow styling to be configured for a lab profile, to provide a custom look and feel.