A tutorial is a content item that explicitly teaches a learner how to build a deliverable off-platform. It is often used to replace a traditional lesson when the LE doesn't support the language or technology the learner is learning. It is a step-by-step walkthrough and should consist of code snippets in the form of markdown that achieve certain functionalities of the deliverable. The tutorial should also have embedded images that showcase to learners what their deliverable should look like once they’ve added a new piece of code. Tutorials should have a link to download starter code at the beginning of the project and the full solution code at the end.
Tutorial vs. Article vs. Lesson vs. Off-Platform Project
A tutorial, like a lesson, has explicit instructions on how to create a deliverable and guides the learner through each step of creating it. Unlike articles, tutorials contain many code snippets and images and expect the learner to work off-platform. Unlike off-platform projects, tutorials explicitly walk the learner through each step of building a project instead of prompting learners to add content independently. Tutorials are maximally prescriptive.
Place in Content
Tutorials can appear as stand-alone content items and within modules to walk learners through building a project.
- Ancillary Information
- Starter Code Link
- Project Creation Information (Set Up Environment)
- Building the Project
- Final Code Link
- Tutorial titles should begin with a verb in the present progressive.
- Example: "Building the Recipe List"
- Tutorial titles should describe what is in the tutorial as well as be SEO optimized.
- Tools like the Keywords Everywhere extension can be helpful in determining what is a popular search term.
- Tutorial titles should follow title-casing standards.
- A tutorial should include a 1-2 sentence description in imperative form. Ex: “Learn how to create SwiftUI TabViews and Sheets.”
- Tutorials should include:
- The version of the language used
- The version of any frameworks
- The OS being used
- How long the learner should expect the tutorial to take
- The author
- The original publish date
- The most recent update date (if applicable)
- The introduction should expand on the description and summarize what learners should expect to learn and build in this tutorial.
- Include an image or gif, if appropriate.
Project Creation Information
- The Project Creation section should walk learners through setting up their local environment for the project that they’ll build in this tutorial. This section can be formatted one of two ways:
- Learners manually create a new project in their local IDE and set it up for what they'll need to build. This should be done for projects that learners will build from scratch.
- Learners download the starter code in a zip file and open it in their local IDE. This should be done for projects with existing code that learners should add to or edit.
- Each section should include images of what the setup should look like.
Note: Mention or provide a resource that shows learners how to update or change the settings in their local environment to be able to set up the project successfully.
Starter Code Link
- Some tutorials will have a starter project for the learner to continue building.
- Starter projects should be zipped and hosted on the Codecademy CMS.
- Learners should be able to click on the link provided to download the zipped project.
Building the Project
- The tutorial should be divided into sections.
- Each section should accomplish a complete idea.
- Text should be broken up with bullet points, images, and code snippets.
- All code snippets should be introduced briefly, then explained in detail afterward.
- Use frequent images to indicate to the learner what the current state of the project should be.
- Do NOT use images of code, as they have poor accessibility.
- Tutorials can contain checks for understanding either using the
<details>tag or embedded assessments.
- The conclusion should include a one or two sentence summary of what was covered and the new concepts taught.
Final Code Link
- All tutorials should have a zipped version of the final project hosted on our CMS.
- Learners should be able to click on a link to download the final version of the project.
- A tutorial should contain embedded images and code snippets.
- Tutorials can also include a video at the top that walks learners through what was built in the tutorial.
Assessments & Learning Standards
- Any new conceptual content that is taught in a tutorial should be associated with a learning standard, otherwise learning standards can be omitted.
- Tutorials can include embedded assessments. Each embedded assessment should be associated with a learning standard as long as the assessment can stand alone from the tutorial and doesn't cover extra information not contained in the Learning Standard.
A consistent theme/voice is present throughout the tutorial.
Language is technically precise and unambiguous.
All videos and art assets in the tutorial are aligned with Codecademy brand style guidelines.
There are no typos or grammatical errors.
The tutorial has clearly defined project outcomes.
If assessments are present, they should only assess what is taught in the tutorial or somewhere else in the module the tutorial is in.
- A tutorial should identify any major prerequisites to its content.
- Starter code should include comments communicating to students where they should add their own code. In beginner tutorials, comments should be more specific and tied directly to certain checkpoints. In more advanced projects, comments might be more general and give students less guidance.
- Solution code should include comments communicating to students where changes in the code have been made and why.