What it takes to write a codelab: behind the scenes of my first experience in Developer Relations
I have always been fascinated by Developer Relations. In fact a number of times in my career I think I have acted as a Dev Rel Engineer however I only discovered Dev Rel for the first time in June 2020 while prepping for my interviews. Back then, during lock-down, I had plenty of time to watch YouTube videos and do Qwicklabs: that’s exactly when I stumbled on Developer Advocacy for the first time in my life. In May (almost two years later) the Angular Developer Relations team offered me the fantastic opportunity to support the development of a modern “Getting Started” journey centered around the introduction of Standalone Components in Angular v14. It was my debut :-)
Heads up: this blog post is not about Angular Standalone Components. If you bumped into this blog post while looking for resources to learn about them, roll up your sleeves and do the codelab! If you decide to keep reading, you will get to know the journey behind it and what in my opinion are the steps needed to publish a Google Developer Codelab.
Step 0: get familiar with the technology. Study, practise, experiment.
Being standalone components a brand new feature of Angular v14 I needed to figure out myself how standalone components worked. This is not always true for every codelab and often the author is also a subject matter expert. I personally believe we tend to explain more effectively fresh new concepts we have just recently absorbed and understood than others that we had time to digest. My recommendation is no matter how good your technical skills are, take a step back and always be in the shoes of those who will try your codelab. Collect the right resources on the web, study, practise, experiment, learn. What did you find most difficult to understand? What techniques/procedures/methodology did you find beneficial? In your opinion what are the main concepts? The challenges you experienced are likely to be others’ painpoints as well, focus on those ones. When you feel confident move to the next step. In step 1 you will need to find a way to make the learning process you went through much easier for others.
Step 1: think carefully about the application you want to build
A codelab is a journey itself, for an hour (or longer) your codelab will take the user into an immersive learning experience.
“Creativity is intelligence having fun” (Albert Einstein)
Think about the old good days at school: wasn’t the subject you got best marks in also the one you liked the most? If we are more likely to learn when we have fun, then the codelab you want to write shall be engaging from the very beginning till the end. How many samples and how-to are available for the same topic out there? Tons. Sure, the clarity of writing is fundamental however in my opinion there is something more important than that: the story you are going to tell.
Because I personally struggle to engage anyone when I am not engaged I spent quite some time thinking about the right application. I wanted the webapp to be: 1) straighforward yet effective in getting developers started with Angular standalone components feature 2) informative and interactive 3) catchy and original 4) integrated with some Google Cloud Platform services 4) easy to build and test. The idea came during a meeting with Mark, a great Dev Rel Engineer and the best mentor to support me in this initiative. While talking about interests and hobbies I showed Mark my online collection of photos that I had built two years before, I remember seeing him impressed by the images. That sparked the idea of a simple wildlife photo gallery app that also featured a “send message” form to contact the photographer (myself!) and a chat window to learn random facts about the animals pictured in the photos. I had to construct the app with the ultimate goal to highlight and explain others the concepts I had previously learnt. Afterwards, I was going to create “Jimbo” the chatbot in Google Dialogflow CX, integrate it in the application and deploy it to Google App Engine. I couldn’t wait to start coding, prior to that though I needed to write a 1-pager to describe the overall idea to the team and receive inputs.
Step 2: build a MVP and write a draft of the outline of the codelab
Once I got general positive feedback from the team I moved on and I developed an early version of the application. I went through several iterations, for example in my initial design I wanted to use a carousel to display the images. When working on a codelab, something to always keep in mind is simplicity. Everything must be intuitive and simple, in my case the goal was not to get a fancy UI up and running. Time is an important factor to take into consideration, codelabs shouldn’t take hours to complete. Focus on what matters most for the developer. For example, version 1 of the app used a pretty fancy black and white L&F that I borrowed online (see below), the result was a complex and unnecessary CSS for the sake of the codelab.
Mark and I agreed to adopt a lighter custom UI and show my own photos as they were not under copyright. Furthermore according to the 1-pager and the initial design, the app would have consisted of 3 pages - home, photos and contacts. That was not a good idea either, on the other hand I made the decision to have it all in one page: photos, a “send feedback” form and the chat dialogue. More precisely the form and the chat window were going to be part of the same standalone component which was going to be loaded and visible only when the user clicked on a button. Lazy loading of components in Angular is a common pattern as it reduces the time to load a page, improves performance and enhances the user experience. In a nutshell, when creating a codelab expect to re-iterate over your app many times. As you start building it you will realise the fundamental and necessary features that must be included and what on the contrary can be omitted to simplify the job of learning for the users.
As the application comes to life it is super important to write down the initial draft of the codelab outline, in other words the structure of the codelab itself. Just like the former, the latter is going to be refined over time and adjusted while writing the codelab.
Things to consider
You will need to make decisions such as whether or not you want to provide developers with an “intermediate branch”. By giving people an initial scheleton to download, they will be able to invest time on the core topics of the codelab without spending too much time on the preliminary steps to get the early app up and running. While this approach works broadly speaking, there are scenarios (like this one) when it might not be a good idea or applicable at all. At time of writing standalone components are a preview feature of Angular v14, so you must create a brand new application using Angular v14 and then remove the “app module”. By deleting the app module there will be no module left but one component which is the app component that must be declared as standalone. As you realise, refactoring the initial app is not just a pre-requisite but a fondamental step of the codelab itself that can’t be omitted. That’s why for this specific codelab we wanted developers to create the whole application from scratch and the codelab will assist them with that step by step. Having said that the GitHub repo contains the complete source code to follow along in case they get stuck as well as the images displayed on the gallery page.
Step 3: write the codelab
Once the app was finalised I started authoring the codelab. Every codelab should start with an introduction which usually includes the following three sections: what you will build, what you will learn, what you will need (such as the development environment needed to build the artifacts or an existing account and the subjects for which a basic knowledge is important). If users are expected to write code, the introduction is usually followed by the environment setup (which outlines the software required to complete the lab) and the GitHub repository. As explained before, depending on goals and scenario, the repository might have two separate branches: one branch with the complete source code and an “intermediate branch” which normally provides an initial starter application on top of which developers will build the rest of the app. Every main section of a codelab should provide a racap of what’s been done until that point and more importantly a brief introduction of what’s coming next and why. The “why” is essential otherwise the codelab will turn into an arid list of steps and actions without a sense of direction. Remember, the ultimate goal is to simplify and streamline the learning curve of a pretty complex subject for the users. Don’t take anything for granted, be explicit and cristal clear. The person who is reading doesn’t have your same knowledge of the matter and context. Use the right terminology and provide images to support your wording, often a screenshot is a lot more intuitive and powerful than a lot of words. Furthermore, for clarity I always recommend to show the complete code example at the end of a series of snippets. Lastly, remind the user to save changes and test as frequently as possible. At last but not least, do you remember when earlier on I stressed the importance of creativity and user engagement when composing a codelab? Find something that can spice it up and hook them in. Give developers something to play and maybe interact with. Add gamification to your codelab, it can be as simple as learning cool facts about sharks and other wild animals through a koala made chatbot!
Step 4: test and then test it again!
Testing is vital, it is absolutely necessary to test a codelab many times while creating it and afterwards during the review process. Once I completed the first version I proceeded to test every step pretending to be a developer who had never seen the codelab before. I followed it line by line, created and deployed the photo gallery app from scratch and edited the codelab whenever I found something incomplete or not clear enough. Peer reviewing is essential, I asked Mark to test it all out for me to discover any bugs and to get his thoughts around my wording. A Google Developer Codelab goes through a very diligent review process which involves engineering and copywriters. Product engineers will improve and enhance the code while copywriters will focus on wording and writing. Every change to either the source code or the codelab can introduce regression bugs. It’s the author’s responsability to merge any changes carefully to ensure consistency. When the codelab is ready to be staged and finally published, the last couple of steps require converting the codelab from a gDocs document into a web viewable format and checking the source code into a Google official GitHub repository.
In conclusion, a codelab is a product of the imagination which requires creativity, time and dedication. Its primary goal is to create a well-lit path forward for developers to learn a specific topic. I believe every learning experience should be inspiring in order to be successful. I wrote the “Getting started with Standalone Components” codelab keeping that principle in mind. Feedback is a gift, try it and let me know what you think!
