Labs Authoring Guide
Lab Development Workflow
| Time prior to launch | Deliverable(s) |
|---|---|
| Preapproval | Discuss ideas with your acquisition editor. Develop your initial proposal.Your proposal is approved! |
| 6-12 weeks | Your instructional designer sends an introductory email with initial guidance and credentials for your private git repository and linked O’Reilly Katacoda profile – as well as a request for a Kick-off Call to discuss scheduling. You start work and have 6-12 weeks to complete all labs, depending on the scope of the work and the agreed upon schedule with your editor and ID. Share labs in-progress with your instructional designer for review and feedback anytime. |
| 4 weeks before publication | Labs due to instructional designer for initial review. Iterate with your ID on any revisions. Once ready, your ID will send final labs to Production |
| 2 weeks before publication | Labs due to production editor for final review and edits. Your PE will reach out to discuss their process and schedule. Iterate with your PE on any revisions. PE prepares the final versions for launch. |
| Launch day | Labs go live! |
Note: If the labs are to be used during a live online training course, the launch day date must be at least 2 weeks prior to the live event date. This allows us time for load testing and scaling needed to keep your scenarios accessible during your course.
Elements of a Lab
Each lab is broken down into 3 main sections:
- Introduction
- Lab Steps
- Outro
Introduction
Your lab’s introduction (intro.md) is broken down into 4 sections:
- An intro paragraph
- A set of learning objectives,
- Target audience and prerequisite skills
- Table of Contents for the lab set
Your intro paragraph should provide context for the skill or concept being taught. Consider the where the skill falls in the bigger picture context of the subject matter as a whole and why this skill or concept is important for your audience to understand.
Your learning objectives should list what skills the learner should be able to do by the end of the lab. This list of objectives often aligns with each step of your lab’s lesson.
Your target audience and prerequisite skills section should include information on what skills your audience should have in order to successfully complete the lab. You can also include your target audience, such as a specific role or roles who would benefit from completing the lab.
Your table of contents section should include a list of all labs (hyperlinked) in the set in the order in which they should be completed.
Steps
All labs and cloud labs contain steps that walk the learner through how to achieve the lab’s skill or concept being taught. Breaking the lab into steps based on learning objective is a best practice to create discrete steps to each lesson.
Steps should include a descriptive title rather than a number (the UI automatically numbers them). This step title should be built into the index.json file rather than added as a header in the step markdown file. As with any instructional materials, it’s important to introduce the concepts and define key terms in each step. You should introduce and explain commands and code blocks being executed, as well as provide brief descriptions of any important output that the learner should pay attention to.
You may enhance your lab steps with figures as appropriate to explain concepts. These figures should be original work, be sourced from an existing O’Reilly text, or have received appropriate permissions from the source to use (this is the author’s responsibility).
Labs exist as stand-alone lessons. While they can be paired with live trainings or books, they should be written without the assumption that the learner has any more context than the necessary prerequisite skills.
The inclusion of asides like notes, tips and warnings should follow O’Reilly Style.
Outro
Similar to your Introduction, your outro should recap what the user learned in the scenario and why it is important. This is also a good place to provide resource links for further exploration or reference.