Hi everybody. I’m Rachel Fenichel from the Blockly team. In this video
I’m going to talk about codelabs and how you can help write them.
I’ll start at the high level: what is a codelab and where can you find Blockly’s codelabs.
Then I’ll move into reasons to write a codelab and how you can get involved.
So what is a codelab?
A codelab is an interactive tutorial written in markdown syntax. Codelabs use a mix of natural
language, code samples, and screenshots to create an interesting and interactive tutorial experience.
The target user of a codelab is following along and running the code as they read.
Where are the code labs?
You can find all of our codelabs at blocklycodelabs.dev.
That link is also at the bottom of this slide.
Right now we have seven codelabs. Soon we hope that there will be more. The contents of the
code labs are in the blockly samples repository in the codelabs folder. Some codelabs also have
associated starter and finished code which is in the examples folder of the same repository.
So why should you write a code lab?
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 that you have.
I've seen our developers talking each other through problems on the forum. I know that many
of you are good at communicating and care enough to walk someone through complicated debugging or
help them find the right way to approach a problem. But sometimes we get the same questions over and
over again and we start to send out links to the last time the question was asked and answered.
At that point a codelab is a good solution. It's a way to communicate something complicated
and also make it easier for the next person to find the answer. I can also tell you from personal
experience that it's really satisfying to be able to answer a question by sending a fully formed
tutorial out without needing to sit down and spend hours painstakingly writing out my answer.
Okay, you've got me hooked. How do I write a codelab?
The flow for writing a codelab is pretty similar to the flow for writing code.
You head over to the Blockly Samples repository and you file a feature request that describes
the codelab that you'd like to see. We'll respond to discuss and refine the idea.
Once the idea is settled, you'll write your codelab in markdown and likely you'll also
take a million screenshots to get just the right ones and then you'll submit it as a pull request .
We'll review it and we'll merge when ready. After that a member of the Blockly team will publish it.
The structure of a codelab is fairly simple. You can think of it like a standard essay:
you start with an introduction which explains what the reader will
build and how they should get set up to run the code. After that there's a series of small steps.
Each step first describes what the code will do, shows the reader the code and then explains any
complicated syntax. Often these steps also tell you what the expected result will be when you
run the code, whether that's some new success, new behavior, or an expected type of error.
at the end there's a summary with links to resources in case the reader wants to learn more.
You don't need to have all the parts of a codelab ready in order to make a feature request .
You can start by just telling us the topic and including links for anyone
else who wants to get started writing. Of course if you have more details
you can include them and that makes writing the final code lab much faster. You can also
decide that you want to show up and write a code lab from a feature request that already exists.
As you can see writing a code lab is a great way to contribute to the Blockly community
and help out other developers. Thanks for watching this video
and I hope to see you at our upcoming developer summit!