Transcript
Kent C. Dodds: 0:00 Hi, everyone. My name is Kent C. Dodds, and I'm super thrilled to be joined by my good friend, Rachel Nabors. Say hi, Rachel.
Rachel Nabors: 0:07 Hey. Good to see you all. I mean not literally, but yes, figuratively.
Kent: 0:12 Good to be seen by all, I guess. Rachel, I always try to think where we met and how far we go back. I seem to remember getting to know you online. I think through Sarah Drasner is how I was introduced to you online. You did a collab or something with her at some point years and years ago.
Rachel: 0:35 Oh, my god.
Kent: 0:36 I just remember getting connected to you through Twitter because of the cool things that you were building back then, and then just following you. I think we met first at, probably, a React conference, maybe React Conf. I'm not sure when.
Rachel: 0:52 Probably in Amsterdam?
Kent: 0:53 Yeah, maybe that was the first time. Anyway, it's been a pleasure to know you online. I'd love for the people watching to get to know you a little bit. Could you just tell us about yourself a bit?
Rachel: 1:05 Wow, it's a lot too. I grew up on a farm in the mountains in Virginia, made comics for teenage girls, had an award-winning career as a cartoonist. I'd always wanted to build video games though, and eventually, there was a big recession, and I got into web development, not the same as video games.
1:28 Then I got into web animation, still not the same as video games. Spoke around the world about it, made some cool things with Firefox, and eventually, found myself here on the React team where I document React and React Native for learners like yours.
Kent: 1:47 That's wonderful. React Native docs, you have finished as much as you can never finish something, right?
Rachel: 1:56 It's a work in progress.
Kent: 1:58 Yeah. Tell me about that experience of just doing a total overhaul of the React Native docs, what was that like? What was it like the process of preparing, and then doing the overhaul, and what have the results been so far?
Rachel: 2:13 It's interesting. It's Cinderella story. You're like, "Wow, I have to join the React team. All I have to do is teach everyone React Native, which I don't know."
2:24 When I arrived on the scene, React Native's documentation was like this old Haunted Mansion full of talking animals who are quite friendly when you got past the spookiness and what's in the West Wing side of things.
2:40 React has a huge community of very helpful people. It also had a completely organic, homegrown documentation that was hand updated. As you can imagine, with the documents not being a part of the release process, some of those reference materials were a little out-of-date, which gave us a bad reputation.
2:58 One of the first things I did was set about cleaning house, that is to say, I went through and I installed metrics. Little thumbs up and thumbs down thing, so we could start measuring people satisfaction with the pages.
3:12 Interviewed learners to be like, "What's your background? Where do you struggle? How do you use them?" Launch surveys that helped me quantify some of the questions that those answers brought up.
3:24 We ran our second annual survey just a few months ago. I'll talk a little bit more about some of the positive numbers that we've seen, because of putting these measurements in place early. After that, to update all the things because there's this huge, amazing, React Native community, so full of people who want to contribute.
3:46 I ran this huge documentation update drive at the beginning of the year, and people came out of the woodwork to go through the source code, update the API references, ended up partnering with some amazing dedicated community members who are now deputy editors who ensure that the docs stay up-to-date.
4:09 We are internally on the React Native team, looking for ways to make those API references automatically update with every release so they never fall out of sync, because if you rely on humans, then it gets tricky.
4:23 The perfect docs are a balance of individual, handcrafted documentation where someone is like, "But what is the best way to explain this to an iOS developer along with hardcore every time there's a change to this API?" The docs are updated. We are blocking on this.
4:43 It's a little bit machine and a little bit of human and a lot of love, and you come up with a great resource. I started launching, all these efforts started to reveal things like we were taking it for granted that people have React experience when they'd be learning React Native.
5:00 33 percent of the people who were filling out the survey, React Native was their first stab at programming ever. Opening up with, "You've heard of React, right? What if you could do React on Android and iOS?" That, you can't expect that people understand React.
5:19 We also found out a lot of people who were coming in straight from iOS or Android development, and we needed to be using language that directly addressed their environments.
5:29 It's not Native platforms, it's Android and iOS, and so this changed a lot of our vocabulary. We created these special fly outs that explain different terms to people who might not be familiar with them.
5:43 Android developers are still growing accustomed to design systems. You might be like, "Oh, like material UI library." Just trying to translate some of these concepts into stories that will resonate with so many different audiences from so many backgrounds.
6:04 That meant building new documents that break down, "What does it mean when we talk about a view?" A view is the atomic component of an interface in Native development, like how you might think of an element in web development.
6:21 A refresh on React, that just introduced people to how to build a very tiny React Native stateful component from the back, just because people might be coming in without React knowledge or rusty React knowledge who just want to get their feet wet. These docs have scored well with the metrics.
6:46 We have more illustrations because we have a lot of visual learners. People have been asking for visual examples, interactive examples. That was part of the documentation drive was to make all our examples interactive, so people could see on the screen what they'd be getting, and tweak and fiddle around with things.
7:05 It just made a huge difference. Our happiness rating across the board, we're not 70 percent since we launched the new docs in January. I'm very pleased with that, but there's still more we could do. We could have a brand new fancy tutorial. I definitely like automating the docs.
7:25 There are so many ways we can continue to move the needle. I do think that going out interviewing learners, having that conversation with the community, and measuring where we're getting it right, and where we're getting it wrong, is crucial to continuing that journey.
Kent: 7:42 That's great, very intentional process. Where did you learn to do that? How did you know a good approach that would lead to improved metrics?
Rachel: 7:54 Part of that comes from running my own courses and workshops, much like you can, but I had a background in UX design because I have a very long and wandering career path. It's like first, she was a designer, then she was a UX designer, then she was a front-end developer, and now she's doing documents. What? These skills pay off.
8:16 The illustration means that I can see where something might make more sense visually. UX design experience means that rather than just going on like that or taking a to-do list at face value when I join a team, I might question it and challenge it and go out and confirm or reject some of these hypotheses.
8:37 Take a very scientific method approach to pretty much everything I do. When you're making things for people, the best way to test them is on people. All of those weird work histories come together to create this approach that I take.
Kent: 8:54 That's just awesome. I'm excited to see your approach applied to the React web documentation. That's where I spend most of my time is on the web-side. What are you looking forward to for React for web, the documentation there, and what are some of the things that you learned from updating the React Native docs that you're able to apply to the update of the React web docs?
Rachel: 9:25 First off, of course, always talk to the audience. The React Native team was active on GitHub and working with their engineering contacts around the React Native community, but they were less connected to, for instance, people who are training their reports how to use React Native.
9:46 With React, the ecosystem is a little different. We have more people doing a larger scale trainings, much like yourself, and you have more people coming in out of boot camps, self-taught, etc. Still, all the same, we didn't want to make any assumptions because we listen in on the conversation on Twitter, we talk to people at conferences, yes.
10:07 At the same time, that's just one subsection of people. Twitter is not a very commonplace to have conversations in Denmark, for instance.
10:17 The conversations in the Danish tech community tend to happen on Facebook and LinkedIn. That's just one example. There are so many. You have to meet people in the field.
10:29 I will put a form out there and be like, "Hey, could I interview you about how you learn React?" People around the world will fill it out. I select people from many different backgrounds and countries.
10:41 English is first and second language and then interview them about, did you know that we have it in a different language? You didn't? Maybe it's not that visible that React has so many translations, maybe that needs to be more front and center on the main page.
10:56 Getting these questions helps me build better surveys that ask more pointed, directed questions. For instance, is English your first language? Do you know if React is translated into your language? Would you read those docs?
11:12 Now, you've got something that you can measure year over year, to make sure that you're reaching everybody you possibly can and you can improve those metrics. It all starts with interviewing people. That's definitely something I'm bringing from my React Native experiences.
11:30 Also, the success of the illustrations and the visuals that we added with React Native docs are going to have a pretty strong influence on the new React documentation. Right now, they read like essays. That is awesome, if you can pay attention for that long. I can't. I don't read science fiction novels, I read graphic novels.
Kent: 11:54 Same.
Rachel: 11:55 I play video games. You're like, engage me, I don't want to read text imaginations.
Kent: 12:01 That's right. For real, I won't read a blog post or anything like that, if it takes longer than a couple of minutes.
Rachel: 12:09 We're not alone in this. There are plenty of whip-smart people who could go very far, very fast, if the documentation slowed down and worked just a little harder to explain some of these things, the way you might on a beautifully designed slide for a conference.
12:27 I know that whenever you have bullet points on your screen when you're giving a talk, you can probably turn those into Visual slides rather than bullet points. The same goes for documentation.
12:39 There are places where I just look at the paragraph and it's like, "Is this the best way to describe what is happening or would a flowchart look better?" Maybe I need a visual metaphor of a hen passing her genes onto her chicks to explain how a component can pass its props down to its child components.
12:58 That's the entertaining metaphor and storytelling that we can do with images, that I look forward to doing with React docs.
Kent: 13:08 That's great. I look forward to seeing the hen and the chicks and those kinds of things.
Rachel: 13:12 We'll see if it makes it through the editings upwards.
Kent: 13:16 That's fun. I totally agree. In preparation for our conversation, I was looking through the React docs, because lots of it, I haven't looked through this for years. The documentation is very good and the approach that they take to explaining things, it's very similar to my own approach to explaining some things.
13:46 Despite that, I still get a lot of questions that are very obviously answered in the docs. People are still asking me and that's telling me that they're not reading the docs, or maybe they're not understanding them.
13:58 I'm looking forward to getting some improvement there so that it's more obvious, or at least, it sticks better for them or something.
Rachel: 14:10 To that end, I want to thank you. You are one of the people that I interviewed working on these docs. I also interviewed people who teach React to understand how they're using the documentation, how are we teaching teachers. I appreciated you taking the time to do that.
14:27 My hopes are that with the help and collaboration of folks like you, we can find out where these things are that people are asking about over and over again.
14:39 That we can definitively address them, and hopefully, free people cycles up to ask bigger questions about things like quick current mode, where do we use that? What's the future of React? How is this going to impact my design system, etc.?
Kent: 14:56 Yeah, precisely. It's nice one. So many people are asking the same question. If we could just put the answers in one place, and then those question askers can think of new questions and the people who are used to be answering those same questions can answer newer and more interesting questions, which is great.
15:18 As part of the rewrite of the docs, another thing that are a big part of that effort will be a transition from classes as the main part to hooks. Right now, hooks is off on its own on the side.
15:35 Any survey that I take of the community, most people are transitioning to or completely using hooks. It'd be nice if the docs reflected that. Can you tell us a little bit about that transition?
Rachel: 15:48 We are rewriting everything from the ground up to be hooks based, but the existing docs will still be archived. You can still go read everything about how classes and the lifecycle work, etc., and the hooks docs live on a transitional upgrade path documentation.
16:07 Don't worry if you're heavily relying on the docs as they are now, they're not going to just evaporate overnight. We're going to hook you up. It does require a bit of a rewrite from the ground up.
16:20 Right now, people are confused. They take training course, they learn about hooks, but when they come to the site, where is the hooks documentation? What's all this classes stuff? Oh, my gosh, it's very hard on trainers.
16:32 You just want to say, if you want to learn more about uses just go here. It's buried because much like React Native's documentation.
16:41 The hooks docs grew organically off the existing React docs is a little subset. The React team initially was very, "Will people adopt hooks? Will they like? Will they trust us? Will this become a thing?" It became a thing. It took off in a huge way.
16:58 If you're building from scratch, you're building with hooks now. The information architecture did not anticipate that, so we got to go fix it.
Kent: 17:11 I guess there's not too much more to say, it's going to happen and it's going to be great. That's great. You mentioned that you have a bunch of people who have come out of the woodwork for React Native on the React Native docs and that's been helpful.
17:30 I want to transition the conversation over for the people listening, what are the kinds of things that they can do, how can they help in documentation in general? What are the kinds of things that people helped with or that were helpful when you were rewriting the React Native docs?
Rachel: 17:48 I can speak to both React and React Native on this. For React, where would we be without our wonderful translation community? It is an amazing thing. We have these people contributing their time, stewarding their local communities, and making sure that anybody anywhere can learn React.
18:08 It's not just React that has translation communities. If you're like, "How do I get my start in open source?" and may be the community is like, "We don't need any more translators." Many different libraries need help with translations. Look at your tool chest, look at what you're using, is there a translation in your language that uses for that particular library? Go ask the maintainers.
18:34 This is something that is easy to overlook, but so many crucial pieces of tech come out of the English-speaking world. It's important that they be made available to everyone, no matter where they are. Everybody should have access to the same tools. That's one thing that you can do.
18:52 I'm assuming because you're listening to this podcast, you probably speak English. If you also speak another language, that is a magical combination.
19:03 Other things that you could do, for instance, with React Native's documentation, we have constantly been accepting both docs, typos, proofread, etc. If you catch where the grammar is wrong, submit a PR for that, a pull request on GitHub.
19:21 There's usually an edit link on every page. That's not just React, but also any open source library, where you can get a GitHub pull request in and have that merged and get your green square for the day.
19:36 If you're thinking, "Well, I'm not much on editing, I'm more interested in design. I don't feel like I could contribute directly to any kind of a library. I'm not an engineer." Believe it or not, we need designers, too.
19:51 React Native's documentation has benefited from many small design tweaks. I introduced little thumbs up and thumbs down interface, but then one designer came by and made it look even better.
20:03 Whenever somebody comes by and is like, "I want to help make this look even more professional and start submitting mock-ups," it's so exciting.
20:15 One of our biggest challenges with the React docs is going to be the design, making something that's first-class and super approachable, but at the same time professional. We just adore it when community partners want to get together and make something that amazing.
20:31 If you're a niche expert at something, for instance, with React Native, we had people who are niche experts at security and testing come in and write guest posts or entire sections in our guides, just explaining these concepts and doing getting started demos, etc. That is a meaningful way that you can continue your niche knowledge into communities documentation as well.
20:59 Lastly, if you are an artist and you love creating illustrations to explain how things work, you still have something you can contribute to documentation. For people with visual learning styles, that is such an incredibly valuable thing to add to their journey. I encourage you to stick your neck out and see how you can contribute, whatever your talent is.
Kent: 21:26 That's wonderful. I appreciate you mentioning, it doesn't have to be React or even a big project. It can be smaller projects. I was thinking about with the translations, lots of small projects just have a README. They don't have a big website or anything.
Rachel: 21:45 So true.
Kent: 21:46 You could go and build a website, that'd be cool. If you want to come in and translate what they have already, here's a suggestion as an open source author myself with many projects.
22:01 It would be totally cool to have a folder at the root level of the repo that's translations, and then a README.whatever, like es for spanish.md, and then you just put that like so. It doesn't have to be this big complicated system.
Rachel: 22:17 That's right.
Kent: 22:18 Translate it there, and then put a link in the README, here's the Espanol translation.
Rachel: 22:25 That's a great point. If you see a growing community like something you use all the time and all they've got is a README and you're like, "Man, they need something better than a README." There is this lovely piece of Facebook open source called Docusaurus, which is what React Native runs on their documentation.
22:42 React documentation runs on some homegrown Gatsby. Docusaurus is this lovely out-of-the-box package, you could just run and it builds a documentation website for you. It's got some built-in initializations for translations, etc., that you can just flick on.
23:02 If you need to go like, "How am I going to take it from README to a site, I don't have enough time?" There are options for that as well and that could be an incredibly meaningful contribution to your favorite project.
Kent: 23:15 Absolutely. Testing Library uses Docusaurus and it's nice to have that. Thank you, Facebook Open Source.
23:26 Another thing that occurred to me, that I suffer, as an open source maintainer, from documentation, and I'd love to hear your perspective on this as well.
23:36 Sometimes, you get these people who are contributing documentation and they've done just a wonderful job, but there's a lot of proofreading and editing that needs to happen, lots of feedback, and back and forth on PRs, and it takes a lot of time. I don't always have that time.
23:55 Another great contribution opportunity is for at least, from my perspective, I'd love to hear what you have to say about this. Another great opportunity is to watch the repo for pull request and provide feedback on other people's pull requests.
Rachel: 24:11 Absolutely. There are some things like voice and tone that you'll always need, the people who are responsible for the repo to sign off on. If you can help grammar check, ask people to expand, even contributing a style guide, and then just checking the pull requests to ensure that they are conforming to the style guide, such a big difference.
Kent: 24:33 Yeah, absolutely. That's great. Is there anything else that we missed about the contributing side to documentation?
Rachel: 24:45 Oh, my gosh, we have covered everything about contributions. Docs are a great place to get started with contributing to open source.
24:55 Additionally, I hate to be so cutthroat about it, it can get you face time with core contributors, because obviously, you need tech reviewers. That can be a wonderful way to get schooled directly from the people who have built the thing that you're writing about. If you want to become a master quickly, writing the docs is a great way to do that.
Kent: 25:23 That's a very good point. I'm glad you brought that up. A lot of my experience early on was derived from those types of interactions, so that's pretty cool.
Rachel: 25:34 I didn't know that about you, Kent.
Kent: 25:37 Yeah, open source taught me a ton. It still teaches me a lot. Recently, it's taught me a lot more about proper interactions and/or friendly interactions, human interactions with other humans. Open source is pretty cool that way.
Rachel: 25:55 I want to know more about that. Isn't it me being interviewed by you, so I get to interview you?
Kent: 26:01 Yeah, maybe we could do that sometime. It's good.
Rachel: 26:04 That would be fun.
Kent: 26:06 Another thing that we talked about before, they're recording here, is a book that I love and that you also seem to love called "Make It Stick." Do you want to talk a little bit about how Make It Stick has impacted the way that you write documentation?
Rachel: 26:27 I'm a big fan of this book. If your learners are interested in spending -- it's an eight-hour audiobook -- interested in having a listen, might change how they approach learning new things.
26:40 I'm a lifelong learner, never going to stop learning, not interested in stopping anytime soon, and the techniques in this book, sort of like, "Man, why didn't somebody tell me this?"
Kent: 26:54 I could have used this in college, pass my classes well.
Rachel: 26:59 Honestly, I joined the team because I was trying to learn React, but without being able to contribute constantly to React because I was working at the W3C writing API documentation, etc., I was like, "How does the web animations API work? Let us sit in a room and talk about that for a long time." That's lovely, but that's not production work.
27:23 I was learning from books and then I forget what I'd read in the book, and I'd be like, "Well, I don't know, maybe I'm just a dummy and I can't figure it out." I knew that can't be true, because, come on, everybody can learn React and programming.
27:37 I've met people who two years out of boot camp, they're senior software engineers and like, "If they can do that, Rachel, what's your excuse?" For me, I found that the thing that was getting me was that I was doing repetition. I read it and I understand it, but without applying it, then it wouldn't come back.
28:02 The thing that Make It stick presses that's been so useful is that it's not enough to just show people and make them do some exercises and move on. It's that you have to bring them back to doing that work time and time again, which is why it's so great to learn on the job.
28:18 That's important for employers to remember when they're hiring people. You're not just hiring someone who can do, you're hiring someone who can learn.
28:26 What you want to see is that they can recall information, perform a task with that recalled information, and that they will perform it even faster after going a period of time without using that information and recalling it. I use this technique to get better at my Zerg rush is playing StarCraft II.
Kent: 28:49 Nice.
Rachel: 28:52 You could sit here and play StarCraft II for three hours straight, just match after match after match after match. The problem is that your brain isn't storing that information, it's putting it into short-term memory and then it flushes.
29:07 When you walk away, you've done a lot of repetitive motions, but you're only going to be able to store so much information for all the hours that you spent on that. When you cram, your immediate recall for the test the next day is probably high, but your long-term recall isn't, because your mind is flushing that information up.
29:25 What you want to do is for me, I'll do three one versus one games and then I will cool it, go away. Maybe watch some YouTube videos of people fighting with commentary on that evening or vary it with reading some of the StarCraft pedia entries about the different units, and then the next morning, I do another three battles again.
29:54 By touching on the information in different ways, here, I'm watching other people, here, I'm playing with my friends, here, I'm reading articles about it, and then limiting my practicing to you don't have to go all out, you don't have to write components for a whole week and expect that you're going to be a master of React the very next week.
30:15 It's better if you just make few components in the morning, will watch a Kent C. Dodds tutorial, read some documentation, go through some code and troubleshoot it with your friends. Just doing it, different ways a little bit over time, can help make it stick.
30:32 We've been looking at ways to incorporate that into the documentation. I'm going to pause here and see if you have a comment to make. I know you're a big fan of this book, and I want to hear how you've been using the teaching techniques.
Kent: 30:46 Let's make sure we don't forget to come back and ask you how you're going to apply this to the Docs. I read Make It Stick, maybe four years ago. It totally changed the way that I do workshops, and teach just in general.
31:02 Retrieval over repetition is a great practice. It's hard for me to do that in a workshop setting, that's a four to six, or seven-hour-workshop.
31:12 I can do the first part of the day, we teach this concept, and then at the end of the day, we teach that concept again. I emailed the authors of Make It Stick, and asked like, "How do you apply this thing?" They gave me a couple of interesting ideas. They were very nice, very helpful.
31:29 A couple of the things from Make It Stick that I applied to my workshops, as well as Epic React, that people who have been through any of it will recognize, is the concept of generation. I don't teach the concepts, I introduce the problem, and then I let them solve it before I teach it. This has been very effective. It's a little painful. Some people don't like it very much.
31:56 I do provide them all the resources that they need to go read up on things, links to docs. I have little helpful emoji friends that they follow along through the code that say, "OK, this is where you're going to do this." Here's a chunk of code that's not related to what you're trying to learn. I'll just give this to you, different things like that.
32:16 At the end, once they've watched...Once their brain has been opened up to the problem, and they've struggled to solve it, then they can watch my solution. It makes way more sense than if I just shown it to them in the first place. When we're all finished, I do the elaboration step where they have to write in their own words, the stuff that they learned.
32:37 They fill out this form that I've got for them, for every single one of these exercises in like, "Here's in my own words, the stuff that I learned." That's also been insightful for me because I see those. It helps me to iterate on my exercises. It helps solidify in their mind what they learned.
32:56 A huge part of Epic React and all my workshops that I've been working on for the last several years is how do I ensure that it doesn't go in one ear and out the other? How do I make sure that they remember this stuff? Make It Stick has made a huge impact on the way that I accomplished that.
Rachel: 33:15 Oh, that's awesome. Documentation, we expect people to use this more as a reference for materials, the thing that you might link out to. We also want to accommodate people who are like, "No, I'm going to learn this by reading the docs," and also expand on certain programming concepts that maybe you might not get if you don't have a computer science degree.
33:38 We introduce a lot of interesting concepts with React that are unfamiliar to people who might just like me come from a HTML and CSS and JavaScript background. We have this brilliant opportunity to unpack some of these things.
33:54 What is the rendering engine? How does that work? The difference between, async -- oh, my gosh. Oh, my goodness -- there's async and then there's...It's you call it one after another? There's you can call several things running at the same time because...Oh, was it and I forgotten the actual technical [inaudible] .
Kent: 34:17 Sequential or synchronous?
Rachel: 34:20 Synchronous, thank you. That is the word.
Rachel: 34:23 There's synchronous and asynchronous code...Oh, my God, I had too much tea today.
Kent: 34:28 You're good.
Rachel: 34:29 It's good to unpack these when people meet them in the field, or at least linked places that expand unpack those things for them. A lot of what we learned how React Native is good to unpack topics that might be new to some people. Even if that's just being able to expand the term and there's an example inline or a glossary that reminds people.
34:52 For instance, for me, I have a glossary sheet on my computer that says that I look things up on like memoization -- memoization is caching for functions that every time I see it like, "What this? What?" Now, this helps me because it's been put into a metaphor that I understand I've explained it in terms of something already know I've built on top of that pyramid.
35:17 That said, we don't have people sitting down for a week with us or even a day. We don't know how long people are going to take. Ideally, we would love for you to be able to come to the React site. Read through all of our content in four hours and get up and running. That would be the dream so that people could feel confident in React within four hours. That's a little hard to get to.
35:42 We have picked up on some things that seemed to work better than others. For instance, people learn faster when they are in a challenging situation. When you throw people out the window, so to speak, they will remember to open their parachute, because it's a challenging situation.
36:02 Some things, for instance, the Linter and React DevTools, we don't teach with them in the documentation as we currently since. React DevTools have a standalone interactive tutorial site. We don't mention them. We don't introduce you to them. We don't show you how to troubleshoot React code when you're working with it.
36:25 We've got this great idea that perhaps the great thing to do at the end of each section is to have people using inline editor, fix the broken component. Check out what the linter says, check out...Inspect it with the devtools. Fix the code.
Kent: 36:44 That's so cool.
Rachel: 36:45 This is my secret way to learn.
Kent: 36:48 I love that's great.
Rachel: 36:51 This is how Dan teaches me Dan's like Rachel triage these issues. I'm like, "Dan, no." Dan's like, "This is how you learn, Rachel." It's good, isn't it? It's so satisfying. Usually, when you're looking at the code, you're thinking, it can't be what I think it is, am I crazy?
37:11 No, I'm seeing things but if it's an interactive editor, no one's looking, you can just test it out right there solve the problem.
Kent: 37:20 I love that. I think that's great. It seems like you're very cognizant of the different places that people are coming from having this glossary and things.
37:32 When we talked a few weeks ago about the React Docs, one thing that you asked me is a good example of other documentation sites. I found one that I thought would be interesting to talk about right now, just briefly, and...
Rachel: 37:46 Next time. Not putting this into my browser at all right now.
Kent: 37:50 It's Discord.js. Discord has an API. There's a module for interacting with that API, mostly for bots, but like OAuth and stuff, too.
38:04 Their documentation, they have two Docs. They have the apiDoc is just reference, very computer-generated stuff but then they have a guide.
38:14 That guide, it is so clear that they understand their audience is not JavaScript developers, the people who are writing Discord bots are not used to writing JavaScript. They're just trying to get their bot to do the thing.
38:31 With that, they're very good at explaining...Here's how you do this simple thing. Here's how we can improve this using some different JavaScript syntax and different JavaScript APIs. If you were experienced with JavaScript, you wouldn't need them to tell you that because you know like, "Those things run in parallel. I can just do Promise.all, and then async/await that thing, or whatever."
38:56 It's very clear that they understand a lot of people come in would have no idea that those APIs exist. They're going to take the time to add some extra stuff to explain. You could improve this a little bit by changing it this way.
39:12 I'm very impressed by those Docs if anybody wants to go through, it's fun to write a Discord bot so there's that too.
39:20 My KCD Discord Community has a bot and you're welcome to contribute to it if you want to.
Rachel: 39:27 I might have to check these out now and build something for the Women React Discord.
Kent: 39:32 It's way easier than you expect. At least it was easier than I expected. Just get your token, a couple lines of code, and boom you can start talking with the bot. It's cool.
Rachel: 39:44 It's really -- how do I put this -- challenging to write React Docs for everyone because there are people learning React who don't have a background in JavaScript. We can't anticipate that somebody who's been working on a design system and building modules for it for either their career will understand async/await they may never have to deal with networking.
40:07 That is one of our challenges is just not taking anything for granted, and yet still diving deep because there will be people who are on the engineering side of things who want to dive deep. This is all old hat and they just want to get to like, "What is the paradigm here?" That is a challenge. I think, like you said, it's something that can be done if you are careful and empathetic.
Kent: 40:33 Exactly. Rachel, this has just been such a pleasure. We have to wrap things up, though. Is there anything else that we didn't talk about? You really want to just mention here before we wrap things up?
Rachel: 40:48 I always forget about this one. People are like, "Rachel, don't you have something to promote?" I wrote a book on UI animation, you can find at A Book Apart if you're interested in building animation with your interactions. It's all about when and where to use motion design so that you can build apps that people love.
41:09 You should definitely check out the React Native and React JS documentation. If you're interested in building for platforms like Android, iOS, even Windows, and Mac. React Native is a great option and you should check it out.
Kent: 41:22 That's great. The book you said, A Book Apart is that what it's called or what's the book called?
Rachel: 41:29 A Book Apart is the publisher. If you go to abookapart.com and look up "Animation at Work," you will find it.
Kent: 41:37 Excellent. That's definitely something. Maybe I should make a book club or something for that.
Rachel: 41:42 That's a great idea. You start with Make It Stick.
Kent: 41:44 Oh, that'd be great. I'll mention this just here at the end. I started this thing called KCD Learning Clubs, where I facilitate getting finding people who want to learn the same thing.
41:58 We put them together in their own group Discord DM, and they can learn things together to have a schedule and everything. It's really cool. If anybody wants to put together a learning club for...It's "Web Animation at Work," is that what it's called?
Rachel: 42:13 Just "Animation at Work."
Kent: 42:15 Animation at Work. Put a learning club for that and then learn animations. That'd be good.
Rachel: 42:21 [inaudible] .
Kent: 42:22 OK. Thank you.
Rachel: 42:23 Then awesome. Thank you, Kent.
Kent: 42:25 Thank you. We'll see everybody later. Bye.
Rachel: 42:27 Bye.