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

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 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 to extend instructions capabilities. Additionally, Skillable Studio supports the following traditional document formats for instructions:

PDF
Word
HTML
XPS

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.

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

Learn more about using Instruction Sets.

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 and Azure DevOps (ADO). 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. Skillable currently supports the following external instruction sources:

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.

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), 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.

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)

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.