Write how-tos in codelab style with walkthrough.so
In my previous work experience as a platform developer at Uber, I had a multi-faceted role. As an engineer, I was responsible for building and maintaining our technology platform responsible for Uber’s trip flow. But this platform was extremely complex with 10s of microservices, mobile apps, data models, and 100s of APIs. So we also had to act like platform advocates/consultants and continuously engage with teams across the organization to help them be successful on our platform for their features and products.
We were a small team. Automating everything was not possible. So to make customer adoption easier and faster, we wrote various forms of “how-to” tutorials explaining platform setup, migration, features, and capabilities. We had used all the different types of tools that were out there — Confluence/wiki, Phabricator, Google Docs, Google Slides, Markdowns, Pydocs, etc. But none of these tools worked as well as we expected.
A lot of our valuable engineering time was lost in this.
Challenges with writing how-tos
How-tos created using the above tools are often ineffective from a reader’s perspective because -
- Procedural content like tutorials/guides with screenshots, code snippets tend to grow longer. For content longer than 2–3 pages, readers find it difficult to follow instructions and end up making mistakes.
- Longer content increases perceived complexity. Readers would abandon the tutorials. (or worst, internal customers will ask for a meeting to understand better 🙄).
- Tutorials can get buried deep into your documentation.
- Wikis/docs/slides can often look very dull and have poor engagement. Readers lose interest in them quickly.
And from the writer’s perspective,
- To create a good tutorial, with annotated screenshots, videos, code snippets, syntax highlighting, etc can take a lot of time. If readers drop out, it is a big wastage of the writer’s efforts.
- Content usually needs periodic updates and poor tooling creates resistance for the writer to keep content up to date.
This problem got stuck in my head for a while. While working on a hack project, I got introduced to — Codelabs By Google. In their own definition -
Codelabs are interactive instructional tutorials
But compared to all previous solutions, Codelabs felt a much better solution.
Why codelab is a great format for how-tos?
Codelab is almost like a hybrid between a document and a presentation. Codelabs are a very effective format for writing anything procedural content — Tutorials, API Tours, Migration Guides, Onboarding, etc.
Google has been adding 10s of codelabs every day and experimenting with this format. Some interesting aspects of codelabs are -
1. It is a proven format of tutorials that have been effective whether it’s a frontend or backend technology. Googlers have written codelabs on almost all of its technologies including Flutter, Android, Kotlin, TensorFlow, Google Cloud, etc.
2. With a lot of content — official documentation, blogs, API tours, code snippets, videos, etc, readers find it difficult to connect the dots between all pieces of information. Codelabs break down the content into logically ordered steps. So they are better for comprehension and it builds muscle memory.
3. Readers often do not finish tutorials in one sitting. Codelabs give a time estimate for each step. This is a small but quite important thing. Having an estimate helps them plan their tutorials better.
4. Codelabs push the focus on interactivity and engagement in the forms of questions/forms and embedding different types of content like podcasts, videos, code editors, etc.
5. The UX is focused on immersive learning experience. No sidebars, ads or useless recommendations while the reader is into the codelab.
A lot of technical writers have shown interest in writing content in codelabs format.
But writing codelabs has not been very straight forward. Googlers have open-sourced their tools used to generate codelabs. However, the tooling requires self-hosting, familiarity with Go and Javascript/CSS, and writing the content in markdown or Google Doc.
Introducing walkthrough.so
To make it easy to write your own codelab style how-tos, I developed walkthrough.so
With Walkthrough, you get,
1.WYSIWYG Editor
Using a nice minimalistic block style editor, it becomes very fast to create the commonly required content blocks like — alerts, images, code snippets, iframes, attachments, etc. This makes writing/modifying extremely easy as compared to any document or markdown.
2. Sharing, Hosting, and Discoverability
Walkthrough makes it easy to share and host such tutorials for your target audience — privately to internal customers or publically to anyone. Walkthrough takes care of putting your images in cloud storage, CDN in the front, and SEO.
3. Styling And Customizations
Everyone wants to showcase their brand and style of their content. We make it easy to make codelabs look styling and customize the looks.
4.Own Your Content
A walkthrough can export your tutorial into your Github repository in Pure JSON format for backup and versioning purposes.
5.Pricing
Walkthrough is entirely free for individuals to use. You have no reason to not give it a try :)
Examples
- How to deploy nextjs app to kubernetes cluster?
- Akka Serverless Shopping Cart
- The walkthrough of the Walkthrough
More examples are available here — Walkthrough Feed
