Writing a Codelab

⁉️ Needs Review ⁉️

• 🐙 This page turned into an invitation to write a codelab + a general collection of tips and guiding questions.

  • ❕ I think it really works! I especially like the section on "Structure". I think it will help people organize their thoughts.

• ❕ Jsyk I changed some header ephasis and added some more links to the process section. As always: feel free to change/revert.

• ❔ Do you have any guidelines for content? For example: no tutorials involving hacks/monkey patching, no tutorials involving third party plugins, etc. If there are I think the "What makes a great codelab?" section would be a good spot to put them.

• ❔ I feel like a total teacher when I say this, so I kinda don't even want to mention it lol. But could you change Writing style > "Avoid walls of text or walls of code." from negative emphasis to positive emphasis? All of your other tips are so positive and motivational, this is the only one that doesn't match.

• ❔ I'm not immediately sure what the "You decide" in "Step ten: [You decide]" signfies. Could you clarify? I think you're trying to say "you decide how many steps your codelab should be" but because the brackets were used earlier to mean [you put in a description] I think it's throwing me off.

• ❔ How would you feel about bumping code style section up so it's right below writing style? Or alternatively bumping writing style down? I think they'd be happier together.

• ❕ Overall, I really like this page! I think focusing on giving people tips was the right approach. It really makes me want to write a codelab! haha

---

Introduction

A codelab is an interactive tutorial written in markdown syntax. We publish our codelabs at blocklycodelabs.dev. Codelabs use a mix of natural language, code samples, and screenshots to create a more interesting tutorial experience. The target user of a codelab is following along and running the code as they read.

Writing a codelab is a great way to contribute to the community. It's a way to share your knowledge and make life easier for the next developer who runs into the same problem.

What makes a great codelab?

A great codelab is focused and readable. It clearly tell the user what they will build and what they will learn, and it walks the user through writing and understanding code to complete a specific task.

Process

If you have an idea for a codelab, you can tell us about it by making a feature request. Include a description of what you want to teach and what you will build in the codelab. We'll discuss and refine the idea. Then you can write it up and submit a pull request for it. Once it's been through review, a member of the Blockly team will publish it.

Writing tips

The rest of this page is a set of tips and questions to guide you through writing a codelab.

Audience

• Who is the target reader?
• What do they already know about using Blockly?
• What are they trying to learn?

Setup

• What is the minimum setup required for the user to run your code?

Writing style

• Use a conversational writing style.
• Avoid walls of text or walls of code.

Structure

As with any writing, start with an outline. This is a good structure for most codelabs:

• Introduction
  • What you'll learn
  • What you'll build
  • What you need to know
  • Setup instructions
• Step one: [A clear description]
  • Explanation/motivation
  • Code sample
  • Expected results
  • (Optional) More explanation
• ...
• Step ten: [You decide]
• Summary
  • What you learned
  • What you built
  • Additional resources
  • Link to completed code (if available)

While you can have more than ten steps, if you're hitting twenty you should consider breaking it into two codelabs.

Code style

• You can write in ES5, ES6, or Typescript.
• Follow the Google style guide