Description and Purpose
A tutorial is a content item that uses the 'Article' content type in Author 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.
Tutorials can appear as stand-alone content items and within modules to walk learners through building a 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.
- All content is written in Markdown and adheres to Codecademy’s Markdown Style Guide.
- All content adheres to Codecademy's Editorial and Pedagogy standards
- Content adheres to Codecademy’s Diversity, Equity, Inclusion, & Accessibility standards.
- All work is original. Sources are cited via links or, for datasets, by following the Dataset Guidelines.
Fields in Author
The description should provide a brief (1-2 sentence) description of the contents of the tutorial.
- The description should include key terms when appropriate (for SEO purposes).
- The description should be written in sentence case.
- The description should be written in imperative form. Ex: “Learn how to create SwiftUI TabViews and Sheets.”
This section should contain the core of the tutorial, including a number of sub-sections:
- Technical Specifications
- Starter Code Link (Situational)
- Project Creation Information (Set Up Environment)
- Building the Project
- Final Code Link
Technical specifications are listed at the top of the tutorial. The specifications should provide the following:
- 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. It should:
- Include an image or gif of the final product, if appropriate.
- Tutorials can also include a video at the top that walks learners through what was built in the tutorial.
- Identify any prerequisites to its content.
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.
- 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 (Situational)
Some tutorials will have a starter project for the learner to continue building. Learners should be able to click on the link provided to download the zipped project.
- Starter projects should be zipped and hosted on the Codecademy CMS.
- Starter code should include comments indicating 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.
Building the Project
This section of the tutorial guides the learner through 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.
- Solution code should include comments communicating to students where changes in the code have been made and why.
The title is displayed to learners at the top of the tutorial and in the course menu.
- Tutorial titles should begin with a verb in the present progressive. The title should describe what is in the tutorial.
- Example: "Building the Recipe List"
- Tutorial titles should include keywords for SEO purposes.
- Tools like the Keywords Everywhere extension can be helpful in determining what is a popular search term.
The slug is used to create a URI for the content item.
- The slug is auto-generated based on the Title field though it can be edited.
Minutes to Complete
This field should be how long you think the tutorial and any embedded elements will take to complete.
- Most individuals read at around 250 words per minute, so this can be used as a proxy while you estimate time to complete. When in doubt, air on the side of being conservative — so make a longer estimate rather than a shorter one.
This field allows you to add an associated author(s) to the item. For now, this field is not publicly visible, but is helpful as a reference.
Curriculum developers use this field to determine whether a Free or Pro audience has access to this item.
If assessments are present, they should only assess what is taught in the tutorial or somewhere else in the module the tutorial is in.
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.
- Any new conceptual content that is taught in a tutorial should be associated with a learning standard, otherwise learning standards can be omitted.