For libraries written in TypeScript, decide if docs will be TypeScript first or JS first. Revamping Redux Essentials tutorial to be TypeScript first. Use fake TypeScript types for better readability. Keep example blocks and code up-to-date. Use Remark TypeScript Tools for doc blocks and compilation. Challenges in writing tutorials: balancing realism and complexity, teaching concepts in the right order, assuming linear learning path. Redux Essentials tutorial: 8 sections, 53,000 words, starts with basic concepts, builds practical app step by step. Reverse engineering process for tutorial development.
That way people might be reading a tutorial and see it and learn a particular concept and then they might actually never have to go to the FAQ page in the first place because they sort of learned that naturally in the process of reading. On the other hand, it is still useful to have specific links to FAQs so that you can point people to that knowledge directly. For libraries that are written in TypeScript, you have to decide if your docs are going to be written TypeScript first or JS first. And this covers both the API references and the tutorials. I actually just got done revamping the Redux Essentials tutorial to be TypeScript first. I always had concerns about it being an extra layer of knowledge that beginners would have to deal with when trying to learn Redux, but ultimately we want our users using Redux, using TypeScript with Redux. And so I put in a lot of effort this year to revamp the tutorial, make the example app TypeScript all the way through, teach TypeScript in the actual tutorial content. And so we really do want people using TypeScript with Redux. Now sometimes in sections like the API references, if you try to show readers the real TypeScript types for your library, they might not be very helpful, especially if those types are complex or very derived. So sometimes you might need to kind of write fake TypeScript types that are simpler and easier for someone to read when they're looking at the reference. TypeScript does allow you to have good information in the JS doc section for a method. And that can actually be extracted and embedded directly in your documentation site. Similarly, it's also good to make sure that the example blocks are actually up-to-date with the current code that's in the repository. And you can actually compile those during the docs build step. And so for both the doc blocks and the compilation step, we use a package that was created by my co-maintainer, Lenz Weber, called Remark TypeScript Tools, which we use the TypeScript compiler to both compile snippets as well as give the TypeScript JavaScript toggle tabs in the references as well.
A few quick things about writing tutorials. As I said earlier, the Redux Essentials tutorial is the primary tutorial that we want to learn Redux with. We take them from zero to building a practical application. And they do it by building a pseudo-social media app, like a little Facebook, a little bit Twitter. It's over 53,000 words at this point. I've been told that I should write a book, and I basically did. And there were a lot of challenges with doing this. When you're writing a tutorial, you want the example app to be realistic and practical enough that it feels like the reader is actually doing something, but it can't be so complex that they are getting distracted and bogged down by irrelevant concepts and code. It's also very hard to figure out how do I teach the concepts in the right order, but it all should still feel like a natural progression as we're just building out this app. We do sort of have to make the assumption that there's going to be a linear learning path, that the reader is going to go through the whole thing start to finish. And then something that I struggled with is for TypeScript. Do we do the whole thing in JavaScript and then show the TypeScript layer at the end, or do we do TypeScript the whole way through? So what we've got is eight sections, 53,000 words, that starts with basic concepts, shows a standalone counter-app example where we can point out all the different pieces and how they connect together. And then parts three through eight build up a practical app, step by step, where we go from adding the Redux store, writing the first slice, dispatching the first action, all the way up through selectors and data fetching and finishing with RTK Query for actually building real apps. In my process, and this won't be true for everybody, but what I did was I came up with the example app, I built the very final version of it from scratch myself, and then I sort of reverse engineered things. If I was to build the app and make the changes over time, what concepts would I want to teach and what order would I want to teach them in? So I very carefully made a Git commit history that showed step by step, here's all the pieces that I would build up over time, and then how I would iterate to add more layers.
Comments