In search of a format for practical guides: CodeLab

Important: Translated automatically from Spanish by 🌐💬 Aphra 1.0.0

It always happens the same way.

When I set out to create some kind of educational material, like a practical guide, I can’t shake this question from my mind: In what format should I create it?

It might seem like a trivial question, perhaps I should focus solely on the content, but the reality is that it’s not.

On one hand, I’m interested in the format remaining relevant and usable for as long as possible. Creating the material takes time and effort that you won’t get back, so it would be a shame to do it with a proprietary tool that depends on a cloud service and over which you have no control. Even if they’re tools that are promoted everywhere and are trendy in the educational field. Maybe the result is very attractive but… Depending on a company’s interests to keep accessing my material? No, thanks. By the way, this argument also includes making it easy to change and maintain in the future… Practical guides in the field of IT become obsolete very quickly.

On the other hand, the format, from my point of view, should be attractive, adaptable to all types of screens, and easy to navigate through. After all, if we manage to make students want to spend time on the content, they will probably get closer to our learning objective.

Until now, I’ve opted for creating guides with Markdown¹ and generating an HTML page from it. You can check the result in this guide I adapted about WireGuard². This way, I’ve been fulfilling the principles that most favor the content creator: a lasting format that’s easy to maintain. Now… As far as attractiveness goes, it falls short. Easy to navigate through… Well, it has a table of contents, but it didn’t seem enough to me.

So I started investigating. From what I’ve found, I really liked how they create practical guides at Apple and Google³. By the way, uncannily similar. But difficult to replicate. Until I came across Google’s CodeLabs⁴. And that did convince me. Easy to navigate and follow, with sections to avoid having too much content at once on the page and adaptable to any type of screen. It even allows students to report errors in the guide. Now I just need to be able to replicate it easily, with a format that lasts and is easy to maintain.

And it exists. It turns out there’s a community of volunteers who have created a tool capable of generating a static site⁵ with a guide in CodeLab format starting from a Markdown file. And now the guide about WireGuard has been transformed to look like this. I think you’ll agree that the improvement is very noticeable.

As always, when I tell you something, I don’t do it without a purpose. In this case, there are two.

The first is that if you know of similar tools that meet these basic requirements and are useful for creating practical guides or similar educational material, you know I’m interested in you telling me about them.

The second objective is to teach you how to create these CodeLabs if you liked the format. For this, I’ve created a CodeLab about creating a CodeLab. It’s only an adaptation of the original created by Marc DiPasquale, to whom I thank here for allowing me to adapt it to Spanish.

I can’t wait to see what you’re going to create next.