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:

  • Instructions Format

  • Instructional Design

• Skillable Features:

  • Instruction Sets

  • Instruction Source (storage location)

  • Custom Syntax

  • Visual Styling

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:

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:

• GitHub Repository

• 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.

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.