google codelabs (my go-to tutorial authoring framework)

NGL; I love using Google Codelabs Tools to author tutorials with!

TLDR; Codelabs makes it incredibly easy to generate interactive self-paced training content with a consistent look & feel as seen on the Google Developers Codelabs site.

---

Ok, still with me? Cool, let’s talk Codelabs for a bit!

Backdrop

I was introduced to Codelabs when I was on the DevRel/Edu team at Starburst. Ultimately, the team launched Starburst Tutorials which is a great example use of this authoring framework. If you squint your eyes a bit when you compare that site with the one that started it all, Google Developers Codelabs, you’ll see a pattern emerging.

The both have little widgets housing titles, snippets, metadata such as duration & date last modified, and that familiar Start button to get the learning underway. They both have their own way to search & filter for specifically what you want while still allowing a bit of flair to make it look as your own.

But once you dive in and hit that Start button, that branding almost completely goes away – and that’s on purpose. The focus is on learning at that moment, not necessarily dazzling anyone with your CSS magic and surely not on selling them anything.

The Snowflake Quickstarts site is yet another good example (on the left below) and I absolutely leveraged Codelabs when pulling together the Datavolo DevCenter (on the right) while spinning up the devrel & edu functions at Datavolo.

Authoring

When writing your content, you have two main options available. You can create your tutorials using Markdown and/or you can actually just author them as a Google Doc. Those of us who are programmers quickly race to the benefits of using Markdown (i.e. easy diff viewing, code versioning, and just generally treating content as code (not a bad thing to think about)), but in practice the Google Docs approach is often better for many – including me.

That’s because a tutorial rarely has more than one author (or rarely has concurrent authors) and usually only has top-rev applicability (much like a website). PLUS, you get all the normal WYSIWYG editing options AND all the normal collaboration features we have all gotten used to when asking folks to review our work.

As an example, feel free to take a peek at a working tutorial I have here. As you’ll see, it is just a “normal” Google Doc, but you do need to consider some styling requirements for everything to end up generating correctly. The Google Codelabs Tools repository has documentation on all of that and is a great place to get started.

Deploying

Regardless of whether you author with Google Docs and/or Markdown, the Tools repo will introduce you to the claat CLI tool that creates basic web assets that you can then deploy into your overarching site. The landing page solutions above are somewhat “fancy”, but you could just house an index page with the widgets to get yourself started like I did with Datavolo DevCenter (i.e. you don’t need tons of searching/filtering options until you have enough content to make that worthwhile).

When using Google Docs (like my example presented earlier) you can even use a preview tool to see how it will look even before running the claat export tool. Check out that tutorial preview here. You’ll need to approve the Google Codelabs integration bits with your Google account that first time.

Here’s a side-by-side peek at authoring and the previewing of that tutorial.

Summary

I’m really digging Codelabs as my tool of choice; repeat, Codelabs is MY go-to tutorial authoring framework. Super simple to use and I just love how easy it is to have consistency across the work I do all while being consistent with other Codelabs authors around the globe. I hope you check it out for your self and feel free to Contact me if I can help you in any way.