Write a codelab
Stay organized with collections
Save and categorize content based on your preferences.
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
in the blockly-samples repository. 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.
read_more
Check out
Technical Writing One for a
quick introduction to technical writing.
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?
If helpful, you can publish starter code
and completed code
in the examples
directory.
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: [Title goes here]
- Explanation/motivation
- Code sample
- Expected results
- (Optional) More explanation
- ...
- Step ten: [Title goes here]
- 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.
Writing style
- Use a conversational writing style.
- Use headings to make the organization clear.
- Use bulleted lists to break up walls of texts.
- Use images and gifs!
Code style
- You can write in ES5, ES6, or TypeScript, but tell the reader which it is at
the beginning.
- Follow the Google style guide
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-05-23 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-05-23 UTC."],[[["\u003cp\u003eCodelabs are interactive tutorials that use a mix of text, code, and images to teach Blockly concepts.\u003c/p\u003e\n"],["\u003cp\u003eContributing a codelab involves proposing an idea, writing the tutorial following provided guidelines, and submitting it for review and publishing.\u003c/p\u003e\n"],["\u003cp\u003eEffective codelabs have a clear structure, including an introduction, step-by-step instructions with explanations and code samples, and a summary.\u003c/p\u003e\n"],["\u003cp\u003eWhen writing a codelab, consider the target audience, necessary setup, and maintain a conversational, organized style with visuals.\u003c/p\u003e\n"],["\u003cp\u003eCodelabs can be written in ES5, ES6, or TypeScript, adhering to the Google style guide.\u003c/p\u003e\n"]]],["Codelabs, interactive markdown tutorials, are published at blocklycodelabs.dev. To contribute, submit a feature request in the blockly-samples repository with the codelab's content and build. After discussion and refinement, write the codelab and submit a pull request for review and publication. Structure includes an introduction, step-by-step instructions with code samples, and a summary. Focus on a conversational, clear writing style with headings, lists, and visuals, following Google's code style guide.\n"],null,["# Write a codelab\n\nIntroduction\n------------\n\nA codelab is an interactive tutorial written in Markdown syntax. We publish our\ncodelabs at [blocklycodelabs.dev](https://www.blocklycodelabs.dev). Codelabs use\na mix of natural language, code samples, and screenshots to create a more\ninteresting tutorial experience. The target user of a codelab is following along\nand running the code as they read.\n\nWriting a codelab is a great way to contribute to the community. It's a way to\nshare your knowledge and make life easier for the next developer who runs into\nthe same problem.\n\n### What makes a great codelab?\n\nA great codelab is focused and readable. It clearly tell the user what they will\nbuild and what they will learn, and it walks the user through writing and\nunderstanding code to complete a specific task.\n\n### Process\n\nIf you have an idea for a codelab, you can tell us about it by making a\n[feature request](/blockly/guides/modify/contribute/write_a_good_issue#feature-request)\nin the blockly-samples repository. Include a description of what you want to\nteach and what you will build in the codelab. We'll discuss and refine the idea.\nThen you can write it up and\n[submit a pull request](/blockly/guides/modify/contribute/write_a_good_pr) for\nit. Once it's been through\n[review](/blockly/guides/modify/contribute/pr_review_process), a member of the\nBlockly team will publish it.\n\nWriting tips\n------------\n\nThe rest of this page is a set of tips and questions to guide you through\nwriting a codelab.\n\nread_more Check out\n[Technical Writing One](https://developers.google.com/tech-writing/one) for a\nquick introduction to technical writing.\n\n### Audience\n\n- Who is the target reader?\n- What do they already know about using Blockly?\n- What are they trying to learn?\n\n### Setup\n\n- What is the minimum setup required for the user to run your code?\n\nIf helpful, you can publish [starter code](https://github.com/google/blockly-samples/tree/master/examples/context-menu-codelab/starter-code)\nand [completed code](https://github.com/google/blockly-samples/tree/master/examples/context-menu-codelab/complete-code)\nin the `examples` directory.\n\n### Structure\n\nAs with any writing, start with an outline. This is a good structure for most\ncodelabs:\n\n- Introduction\n - What you'll learn\n - What you'll build\n - What you need to know\n - Setup instructions\n- Step one: \\[Title goes here\\]\n - Explanation/motivation\n - Code sample\n - Expected results\n - (Optional) More explanation\n- ...\n- Step ten: \\[Title goes here\\]\n- Summary\n - What you learned\n - What you built\n - Additional resources\n - Link to completed code (if available)\n\nWhile you can have more than ten steps, if you're hitting twenty you should\nconsider breaking it into two codelabs.\n\n### Writing style\n\n- Use a conversational writing style.\n- Use headings to make the organization clear.\n- Use bulleted lists to break up walls of texts.\n- Use images and gifs!\n\n### Code style\n\n- You can write in ES5, ES6, or TypeScript, but tell the reader which it is at the beginning.\n- Follow the [Google style guide](https://google.github.io/styleguide/jsguide.html)"]]