Onboarding React Developers to Typescript

Hi there, my name is Silvana Santos and today I'll be walking you through what I believe are some best practices for onboarding React developers to TypeScript. So a little bit about me. I am a software engineer at Codecademy. I work in React, TypeScript, Next.js as well as some back-end technologies and I'm passionate about knowledge sharing and advocating for budding engineers at my company. This is something that's particularly important to me because it wasn't that long ago that I started my own journey to software engineering. So I'm always eager to support those in their journey as well. And so I hope that today I can offer a bit of a fresh perspective on onboardings since it's normally something that engineering managers or senior engineers handle.

So the agenda for today. First, we'll discuss some pain points that many engineers, including myself, face when they are learning TypeScript for the first time. Then we'll identify some principles that you can follow to ensure that you are creating an effective onboarding experience. And then most of our time will be spent examining what an effective onboarding experience might look like. And then we'll do a quick recap of all of the key takeaways from today's session.

So pain points. From the moment that an engineer first opens up a TypeScript file, they can start to feel pretty overwhelmed. When you aren't familiar with the syntax, TypeScript can look pretty scary. The files are much more robust than the JavaScript files that they might be used to. And so becomes really difficult for them to identify the syntax that they're already familiar with versus the syntax that they aren't familiar with. And once they get past that initial shock and start actually doing a bit of work in TypeScript, they can start to feel like TypeScript is working against them, not with them the way that so many people claim it will. And this is especially true for engineers who have never worked with statically typed languages. It can feel like you fix one compilation error and all of a sudden ten more appear in its place. So, it can get pretty frustrating.

So, with those pain points in mind, we can establish some principles that will help us shape our onboardings. These are just three principles that I try to keep in mind when I'm building these experiences. So, first is create a safe space. This starts with encouraging learners to ask questions and reach out for help. Even beyond the onboarding itself. But it can be much more than that. Sharing your own experiences, learning a new language or technology and talking about the struggles that you face along the way can really go long way in comforting an engineer as they are learning Typescript. The second principle that I try to follow is drawing parallels. Whenever possible, it's great to connect the things that they are trying to learn to the things that they already know really well. So, for example, if you're trying to teach a Typescript concept, it's great when you can connect it to work that they've done in React. Or if the engineer has worked in Java before, then you can connect the Java syntax to the Typescript syntax. The third principle that I try to follow is enable discovery. Most people don't retain information very well when they're just passively listening. It's much better to have people try things out on their own. So, whenever possible, I try to help learners discover the power of Typescript on their own.

So at this point, we've discussed pain points that learners can face along their learning journey.

And we've also identified some principles that we can follow to make a more effective onboarding experience. But you might be thinking, what is this actually going to look like in practice? Well, let's dive into that. So, there's obviously many different ways that you can format an onboarding experience, but I have found that workshops really embody the principles that we just talked about. So, this is the format that I normally follow.

The first 5 to 10 minutes are used to kick off the meeting. It's a time for everyone in the session to get to know each other. And then you can introduce what TypeScript is and why it's valuable to your company. Then a majority of the time will be spent pair programming. The engineers in the session will be broken up into small groups where they will work together to accomplish small challenges. And then the final 5 to 10 minutes will be used to wrap up the session. This is a time for you to address any lingering questions, share resources for engineers to continue their learning journey, and collect feedback on their experience.

So as I said, the biggest and most important part of the onboarding experience of the workshop is the pairing time. So there are two things that you can do to ensure that this time is purposeful. The first is that you should ensure that each group has two to three learners and one mentor. The session should be driven by the learners but the mentor is there to help unblock them or answer any questions that may come up as they are working through the challenges. The second thing that you should do is provide learners with a document that guides them through those challenges and we'll take a look at what documentation might look like later on.

So at this point you've heard me mention challenges a few times and you might be wondering what is a challenge? What does a challenge look like? So I break up challenges into three parts. The first is the prompt this is telling the group what task you want them to complete. Then that's followed by a hint or multiple hints that will help them when they get stuck. This is a chance for you to share resources on the topic or provide them with clues to help them make progress. And hopefully after they receive some hints and maybe some guidance from the mentor they're able to come up with a solution and they can check their solution against the answer which is just a code snippet of the solution.

So in order to get a better sense of what a challenge might look like let's focus in on the topic of function annotations. So whenever you're trying to build a challenge around a specific topic there are two things that you'll want to ask yourself. First is, what might make this topic difficult for learners to understand? In the case of function annotations there are two reasons why learners might find it difficult. The first is that writing function annotations requires you to have the TypeScript fundamentals down and when you've literally just learned this a few minutes ago or 30 minutes ago it can be really hard to recall that information and also be asked to build on top of that information. The second thing that might make function annotations difficult is that you can annotate functions using many different syntaxes. So it can be really easy for learners to jumble up the syntaxes and so at this point you should ask yourself how can I address these difficulties? How can I make this topic more digestible? And so in the case of function annotations there's two things that you can do here. First is ensure that your learners have gotten the basics down before taking on this challenge and so that means you should build a challenge that covers the basics and have them do that first. The second thing that you'll want to do is to break up this challenge into multiple parts and that allows you to cover different syntaxes in each part. So let's take a look at what the challenge might look like.

So part A asks the learners a list of functions using a function type expression. So you can see here we have different functions that all have different inputs and different outputs to get them practicing the syntax with a bunch of different functions. And so if the learner gets stuck along the way, the first thing that we do is that we direct them to the docs. If that doesn't help, then we give them a little breakdown of the syntax and try to connect it to something they already learned in a previous challenge.

So here you can see that we're showing them how they are used to, how they should be declaring a basic string variable, and then we're comparing that to how you would use that same annotation on a function. So in this case, you just have your variable name followed by a colon. And whatever follows the colon is the type. And then whatever follows the equal sign is the value, the same way that you would normally do it in JavaScript. So hopefully, with those hints, they are able to come up with their own solution and compare it to our answers here. And one thing to point out is that these links that you have seen in the previous slides, they lead to a TypeScript playground, so that this is very interactive and they have a place to sort of play around with code. Yeah. So as you can see here, we provided them with the answers so they can see how the syntax will look with different types of functions that all have different inputs and outputs.

Onto part B. So this challenge asks learners to add parameter and return type annotations to the same list of functions that they examined in part A. And so this allows for continuity and also makes it a lot easier for learners to compare the different syntaxes. And so, again, with the hints, we direct them to the docs. We want to get them familiar with working in the TypeScript docs. But if that is not enough, then we also provide them with a little breakdown of the syntax. And, again, we're sort of highlighting that the syntax here by saying you are annotating the parameter here the same way that you would in a variable declaration. And then we have this new sort of syntax of having a colon after the parameter and whatever follows that colon is the return type annotation. And so, once again, with those hints and with the help of their mentor, hopefully they arrive at their own solution, which they can compare to our answers that we provide them in the document.

So, at this point we have given them enough information for them to be able to annotate React functional components. Now, obviously, there's a lot more to function annotations, so we could definitely add more things to the previous challenge. For example, we could tell them to refactor their annotations using type aliases or something like that. But, as I said, at this point they have the bare minimum knowledge to be able to annotate React functional components. So, again, for this topic, we're going to want to break up the challenge into multiple parts. So, part A, ask the learners to create an interface that defines the shape of the props in the component. So, again, we want to make sure in the component. We want to make this digestible. We start with a small portion of the task. As you can see here, we have a component called curriculum card. And all it does is it takes in an object which contains a title, a description, and displays that. So if learners get stuck in trying to annotate or in trying to create the interface for the props of that component, we first guide them to the docs. But here we also give them a little clue and we tell them if you're not sure about the shape of the props, how about you take a look at where we're deconstructing the props. That might help you out. And so hopefully with the docs and the hint there, they're able to come up with their answer and come up with this interface here. And also one thing to note is that at some point, maybe in that challenge that we had on the beginning with basics, you should cover interfaces. This should not be the first time that the learners are seeing interfaces. There's just not enough time in this workshop or in this talk to have shown that, but just want to caveat that this should not be the first time that your learners are seeing interfaces.

Cool, so on to part B, which asks learners to annotate the component using either a function type expression or a parameter slash return type annotation. So again, using the same component from part A, this time we provide them with slightly different hints.

So again, using the same component from part A, this time we provide them with slightly different hints. So no docs this time. What we tell them is, that first, they're going to need the interface that they created in part A. So that's a big hint. And then second, we actually ask them a question first. We ask them, what is the return type of a React functional component? And hopefully you would have this in some sort of toggle, so that they have a minute to think about it. And if they're not sure, we sort of give them the answer here. And we say, a React node, that's the return type. Now, that's not completely accurate, but we're sort of trying to nudge them in that direction. And maybe further down the line, we can explain that that's not completely accurate. And so, we give that caveat to them. Don't worry, you might be a little confused about where this is coming from or what it is. Don't worry about it for now. One thing at a time. And so, again, we provide them with the answer here. In the link, I show them how to do it with the two different syntaxes. But just for the purposes of this slide, I showed one of the syntaxes.

Amazing. So, after going through this process of sort of building the challenges, talking about the difficulties and each of the topics. This is what the workshop would look like. We would have challenge one, which covers basic types. This is not something that I explicitly showed in the session today. But it was something that we said that they need for challenge two, which covers function annotations. And then once they have that knowledge of function annotations, they should be in a spot where they can take on challenge three, which is React functional components.

And so, obviously, there's so many things that you can cover in this session. You can build out function annotations more. You can add other topics. You can really tailor this to help enforce the best practices that you use at your company. So, for example, you could add a challenge four, which covers generics, and that will help prime them for challenge five which covers which revisits React functional components, but this time introduces them to the React.fc type. So, that's just an example of maybe how you would want to build on top of this sort of base that we covered here today.

And so, let's go ahead and recap everything we covered. First, learning TypeScript can be tough. I can tell you firsthand that TypeScript was not something that was intuitive to me. It took a lot of tries for me to have that ah-ha moment. So, with that in mind, you should try to make your onboardings a safe space where your learners can get hands-on practice with TypeScript. And workshops can be a really great format for accomplishing that goal. And when you are creating workshops, if you decide that, that's the right format for you, you should slowly expose engineers to TypeScript concepts, and that should all culminate in a React use case as we saw here today. So that is all I have for you. I appreciate you taking the time to watch my session. I hope that you figured out some ways to improve or maybe if you're building from scratch your onboarding experiences.