Rachel Nabors works at Facebook on React and React Native documentation. We interview Rachel and get the scoop on what makes for great documentation.
Rachel Nabors works at Facebook on React and React Native documentation. We interview Rachel and get the scoop on what makes for great documentation.
This episode brought to you by Infinite Red! Infinite Red is a premier React Native design and development agency located in the USA. With five years of React Native experience and deep roots in the React Native community (hosts of Chain React and the React Native Newsletter), Infinite Red is the best choice for your next React Native app.
Show Notes:
Helpful Links:
Connect With Us!
Todd Werth:
Welcome back to the React Native Radio Podcast. This week's episode is brought to you by the number 12. Episode 178, Documenting React Native with Rachel Nabors.
Jamon Holmgren:
Hey everyone, welcome to React Native Radio Podcast, where we explore React Native together. I'm your host, Jamon Holmgren. I'm joined by two of my three awesome co-hosts, Robin Heinze, how are you doing this morning?
Robin Heinze:
I'm doing really great.
Jamon Holmgren:
Very cool. And Harris, how are you doing today?
Harris Robin Kalash:
I'm doing good. Thank you.
Jamon Holmgren:
Very cool. And today we have a very special guest from Facebook, Rachel Nabors. Rachel lives in London. Is that correct? Do you live in London?
Rachel Nabors:
Jolly old.
Jamon Holmgren:
Very cool. I can tell from your accent, obviously.
Rachel Nabors:
I'm an American Wolf girl abroad.
Jamon Holmgren:
Yes. And you work at Facebook on React and React Native Documentation. How are you doing today, Rachel?
Rachel Nabors:
I'm doing pretty well. The sun is setting here in London. It was threatening to rain all day, it decided not to. Real pleasure to be here on the show today, and great to meet you all.
Jamon Holmgren:
We really appreciate you coming on. As you know, we've recently relaunched React Native Radio, and we're excited to have some new voices come on here and to give their perspective. I'd like to start by just asking a little bit like, how did you get into coding and what led you to where you are today working at Facebook, working on documentation?
Rachel Nabors:
Wow. How did I get into coding and then documentation? That's a really long story. I feel like a lot of people are going to tell you a story about how they went to college and chose computer science as a major. My story is actually, I made comics. I couldn't afford college. I was just a kid living out in the farmlands in Virginia. And I connected to people through the internet, making comics.
Rachel Nabors:
I built websites to promote comics to my audience. And I did that for a long time. Then I needed to get some jaw surgery and that requires health insurance because America. And I said, "What skills do I have that I can get paid for?" And it turned out that in Raleigh, North Carolina, there were a few shops that would pay for web development.
Rachel Nabors:
I ended up getting type cast as a designer because when people saw my comics, they thought, "Artist, illustrator, designer, visual." So, I was strangely herded away from my true passion, which was mucking around with PHP and CSS and MySQL and herded slowly back toward Photoshop. It would take me many years to realize I actually hate being a designer.
Rachel Nabors:
I hate making the logo bigger and I hate changing the color to be the one your boss thinks is prettier. I like making things work. I like making things people play with. I wanted to make video games when I was a kid and I did not know that was a job until very late in life. But anyway, made comics, got into web development. It was the recession, so people weren't paying much.
Rachel Nabors:
I realized I could probably make as much traveling and speaking about the things I was passionate about, CSS animations, and transitions and motion design on the web and working on the web animations API with the W3C, which all of this is not amazing amounts of income, but compared to what I was making at the end of the recession, I was like, "Yeah, I can pull this together. It's fine."
Rachel Nabors:
And I did that for a long time. Traveled internationally, made cool things like dev tools challenger with Firefox to showcase their animation tooling. It was good. And then I ended up realizing, "Well, maybe I could do things like this at companies that are big enough to have roles for people like me." I ended up working over at Microsoft on Edge for a while.
Rachel Nabors:
I did a little stint on animation and bookings design systems in Amsterdam. And then I had the opportunity to come here and work with the React team. I was really excited about it, had to choose between working in Menlo Park or in London. And given I'd just been in Amsterdam, I was like, "London." Now that we're in a pandemic, I'm like, "Was that the right choice? I don't know."
Rachel Nabors:
But long way around to saying things that connect my previous career as an award-winning cartoonist for teen girls with my current trajectory is, I love deeply understanding things. I love deeply understanding people. I love deeply understanding systems.
Rachel Nabors:
My mom was a burned-out systems analyst. She warded me off of code quite a bit as a kid. I think she didn't want me to burn out in the long term. But I ended up in this situation where my job is to deeply understand and communicate things. And as a former cartoonist, I'm pretty good at doing that visually and verbally.
Jamon Holmgren:
So, your background doing cartoon illustrations is very fascinating to me. Do you ever use that in your documentation efforts? Do you create illustrations for your documentation?
Rachel Nabors:
Absolutely. It's amazing. There's so much evidence that shows that using visuals will help ideas stick when you're teaching. We talk about how people are visual learners and they're example learners and they're verbal learners. But the truth is that the human brain switches off between all of these things. And depending on your current cognitive load and past experiences, you may lean more on one of those than the others.
Rachel Nabors:
Nothing's hard-coded, we change a lot. I used to be a very visual learner. Now I'm a person who learns by doing. Pair coding is my favorite way to learn. It really sticks when I have to do it with somebody else. But for visual learners and for people, even verbal learners, having a visual summary of a concept can just really burn it into long term recall in ways that just words or actions can't.
Rachel Nabors:
In this regard, back when I used to speak on these topics, whenever I'd see a slide that was bullets, I would always take that slide and try to represent each bullet visually so that people wouldn't read my slides, but they'd see a picture and I'd be talking over it. Even if that picture was some code, it's more important to explain things by showing than just by telling.
Robin Heinze:
I think I would imagine that as a person writing the documentation, making sure you have the ability to represent what you're trying to explain visually is probably also really important to your own understanding of what you're trying to document. I think I've sat down to try and explain how to do something and realize I didn't understand it as well as I maybe thought. So, being able to draw a diagram really cements your own understanding as the documenter as well, I'm sure.
Rachel Nabors:
It's an excellent tool for hammering out the finer points of things. I was really getting caught up in what exactly is the render phase and the commit phase. I was having a total bear cat moment where I was like, "Well, where exactly does this go? I don't understand."
Rachel Nabors:
And so, finally I just started sketching out doodles and I would hand them to Dan and I'd be like, "Does use effect go before or after the dome gets rendered by the browser for use layout effect." There are several revisions. I draw, I send. It comes back with like, "Well, that's not quite right. This is what this happens." I send it back. And finally, "Yes, this is the flow."
Rachel Nabors:
And I'm like, "Good. I'm going to turn it into an SVG and put it on the site now." So, it's an iterative process, but it's funny that you should mention that. Whiteboarding is the one thing I fear the most about interviews because it's like performance art and it's just utterly terrifying.
Rachel Nabors:
I used to absolutely fall apart in standardized testing as a kiddo. But when you think about it, the real ask is, can you draw with me? Can you go through this? Can you give me a shape of something on this board and draw with me and we can figure out a solution together?
Robin Heinze:
White boarding sessions have been some of my most vivid memories of the a-ha moment of finally understanding a concept. I think it's really powerful to be able to express something visually.
Rachel Nabors:
It is.
Jamon Holmgren:
We have so many questions for you, Rachel. I don't know if we're going to get through them all.
Rachel Nabors:
Let's try.
Jamon Holmgren:
But we will do our best. Before we get too much further, I want to say that this episode is sponsored by Infinite Red, which is my company. The premier React Native consultancy, if I do say so myself, with deep roots in the React Native community. In fact, recently I tweeted out all the things we do in React Native. For a team of about 25 people, it's quite a list.
Jamon Holmgren:
Check us out at infinite.red for your next React Native project. And today, as you can probably tell, our main topic is documenting React Native with Rachel Nabors who is a perfect guest for this topic. Without further ado, let's dive right into the questions that we have for you.
Robin Heinze:
So, for many of us who are building things with code that we need to document, I think one of the biggest hurdles is how overwhelming it can seem. And so, what advice would you give to someone who just doesn't know where to start in documenting what they've built?
Rachel Nabors:
That is a very good question. I think a lot of times our first steps toward documentation happens when we have to onboard a new collaborator who has a what's this mean? What's that do? I usually start by creating a cheat sheet during those conversations.
Rachel Nabors:
Like these are the things that they're getting stuck on, and then I'll end up publishing that cheat sheet somewhere, usually in a read me or an internal Wiki or something like that. I actually just published something for a tutorial for making tutorials. I know, super meta and recursive. It really does get recursive when you get into it.
Rachel Nabors:
And you find yourself repeating yourself over and over on certain things. Maybe it's in Twitter threads, maybe it's in Github issues. Don't repeat yourself, put it someplace you can link to. Whether that's your read me, eventually, you're going to end up with a super long pile of blog posts or a read me that's just way too deep to get through.
Rachel Nabors:
And then you might want to look at something a little bit more structured. One of Facebook's open source projects, Docusaurus is like an out of the box documentation hub. It doesn't do automated API docs generation, not yet at least, but this is what we've run reactnative.dev on. It's out of the box. You can have different sections for your API, for your docs, for your tutorial.
Rachel Nabors:
And this is just a kind and friendly way to get started with things. I think Relay uses it and I think it's Recoil who uses it. It's very popular with a number of open source projects, both from Facebook and abroad. And I would say that if you need something that scales up a little bit, that's a good place to start moving that tribal knowledge into.
Harris Robin Kalash:
Could you repeat the name of that?
Rachel Nabors:
Docusaurus.
Harris Robin Kalash:
Docusaurus. Okay.
Rachel Nabors:
Like roar.
Robin Heinze:
I've actually played around with it, and I don't think I realized that it was a Facebook tool. That's really cool.
Rachel Nabors:
Surprise.
Robin Heinze:
Surprise.
Jamon Holmgren:
I'm sure the documentation for Docusaurus is amazing, right?
Rachel Nabors:
It actually is. You read the docs and you're like, "That was easy." It's like, of course it was easy. It was created by-
Robin Heinze:
Is Docusaurus is documented using Docusaurus?
Rachel Nabors:
Yes.
Robin Heinze:
Of course, it has to be.
Harris Robin Kalash:
I've never used Docusaurus, so maybe for people who haven't used it, could you maybe ... so, is documentation maintained as code? Is that-
Rachel Nabors:
It's markdown files. Honestly, you get into an interesting place. Once your surface area gets big enough, it can be hard to keep things up to date. React Native struggles with this because it's got a huge surface area. So many components and APIs and every release we have, something changes.
Rachel Nabors:
Right now, anytime something changes, somebody ... right here, so much thanks to our open source contributors on repos who keep an eye on this. I'm going to give a special shout out to Bartosz for handling a lot of our releases, picking through and finding these changed things and applying them by hand to the docs.
Rachel Nabors:
That doesn't bite like for something that maybe like React has a much smaller surface area, that makes sense. But with React Native, we're talking about dozens upon dozens of pages and one little property now has a different default value. Whew. It's easy for the docs to slip and run out of date. So, in this situation you have two options or three options.
Rachel Nabors:
You can do it by hand like we've been doing with React Native as of late, which is very labor intensive, but it's very solid. You can automate it. You can have it so that there's a bot out there that parses the API and just spits out page stubs or does documentational comments around it. Or you can block releases until everything is documented. You can guess which one of those typically ends up getting used.
Rachel Nabors:
And this is why documentation has a tendency to slip out a date and unless it's built into your projects process early. So, if you're thinking about docs now, think about how you want to scale your docs in the future. Do you want to make it a part of the engineering release process? Do you want to make it something that's completely maintained by human beings?
Jamon Holmgren:
I'm one of the team that maintains the React Native web view, which was extracted from React Native core. I actually extracted it, I think a little over a year ago, from the core into its own package. And I guess I've always had, or for a long time, I've had a philosophy that if I put a docs folder in the repo itself, and then every PR I just ask everybody, can you also update the docs with this new API or this change or whatever, before I merge it?
Jamon Holmgren:
Then I don't have to think about it so much. But obviously that's great. That's good at keeping the API reference from getting out of date, but that's really more of it's a mechanical part of it.
Jamon Holmgren:
It's like the basics. There's also other types of documentation, like tutorials and walkthroughs and philosophy even behind how you might approach something like that. So, how do you determine what types of documentation are needed for a particular package or open source project?
Rachel Nabors:
That's a good question. I got to be honest with you, I'm a rule of thumb kind of person. And the way it usually breaks down is into APIs, this is the nitty gritty. This is where all the deep technical information and the shape of the information goes. There's the tutorial. This links to the nitty gritty.
Rachel Nabors:
So, it doesn't explain how an individual method works, it links to the API doc when the method is mentioned and shows you how all these different things work together by holding your hand and walking you through a sample. And then there's guides. And these slow down and explain how everything is working together.
Rachel Nabors:
This is the sort of thing you read on your iPad at lunch, and it's not an exercise you do in a workshop or in an hour on the weekend. It's not an API reference you hop into on a daily basis. It's something you read when you get started and you probably don't revisit it often, unless there have been major changes or new releases added new sections.
Rachel Nabors:
And we do have the stats with reactnative.dev and actually with reactjs.org that support these usage patterns, which is why they show up over and over again in documentation around the world.
Harris Robin Kalash:
Interesting. So, other than maintaining documentation as the surface area for an API changes, how do you know that your documentation is achieving its purpose? Do you wait for someone to comment something? Or how do you deal with that? How do you test it, I guess?
Rachel Nabors:
That is also a great question. This is tricky because the one thing about docs and developer advocacy is, it's hard to measure the impact they're having on how much people are able to get their work done and how much they like doing their work. If only I had some dopamine centers in every user's brain so that I could just be like, "Yeah, they visited the site.
Rachel Nabors:
"They got unblocked. It was good. Where's my raise?" I am a person who loves numbers. I love watching numbers change. I love metrics. But metrics can be misleading. Like when you go to Google Analytics and it shows a lot of people are visiting one page, are they visiting it because it's useful? Are they visiting it because somebody popular linked to it saying it was terrible?
Rachel Nabors:
Or are they visiting it because they can't get unstuck and they don't know where else to go? You don't have any context. You've just got numbers. One thing we did with the React Native Documentation, and now with the React JS Documentation, we put little thumbs up, thumbs down ranker on that. And it's not too complicated. It's just a little event that goes into Google Analytics.
Rachel Nabors:
And I can then use those metrics to see what are our highest traffic, but most negatively ranked pages, which those are like people aren't liking that. We're doing a bad job. I can overall grab the average satisfaction people are having with the docs from that. And I can compare that against survey data.
Rachel Nabors:
I think it'll be over by now, but we are running our first React survey ever, which is based on the success that we've had with the React Native survey, which had its second run earlier this year. These surveys provide qualitative feedback, whereas metrics provide quantitative feedback. And between these two things, we can get an idea for, people are now 70% happier that the React Native Documentation has been brought up to date.
Rachel Nabors:
It's lifted the overall happiness scores for the site. And that is a good sign and we should probably be aiming to get them even higher. Here are the things that worked, here's what didn't. But we might not see those same numbers reflected in the survey, which has a range of different users as the docs that are being metriced on, that people were being unhappy with were being used by people who visited the site frequently, daily users hitting those API docs.
Rachel Nabors:
So, figuring out if you're doing your job right is nuanced. It requires you to actually interact with people. Like I'll often just show up and be like, "Hey, can I just hang out with you today and see how you do your job?" And I just follow along and see what they're referencing, where they're going for things.
Rachel Nabors:
I know it's a little creepy, but we used to do this all the time back in UX research, and you can do it with your docs too, just pay attention to what somebody is doing on their own. And if they aren't turning to your documentation or can't find it, ask questions about how you can do that better.
Rachel Nabors:
And install measurement techniques ahead of time. You don't want to be just looking at Google Analytics at the last minute, you got to install some feedback metrics and run some surveys and ask deep boolean answered questions on them.
Jamon Holmgren:
That's fantastic. I really like how you use not just the raw numbers, but also the emotions that are associated with that documentation when they're there. And you touched on this, the survey, this was mentioned, I first learned about it in an issue that you filed in the reactjs.org, the website repo, which the title was New React Docs. So, this is a big initiative that you are undertaking.
Jamon Holmgren:
From what I understand, it has a lot to do with moving away from the class component centric examples and documentation, towards the new Hooks syntax. Can you talk a little bit more about this? And it seems like a pretty big job in front of you.
Rachel Nabors:
It is, don't remind me. I'm just kidding, it's a lot of fun. I always say when I'm taking on one of these projects, it's like I've been commissioned to make a book. It's my job now. If anyone's ever written a book before, and I'm sure a lot of people in the audience have written a book or it's equal, you know it's a big undertaking from the outline to the individual chapters, to the examples, to the publishing process.
Rachel Nabors:
It can take a long time. Fortunately, it's not just me working on this. We've also got Dan Abramov and wonderful contributors, both inside and out the company. But in the end, making a book usually comes down to an editor and an author and maybe a co-author or two. And that's sort of what this is. Now, you might be thinking, "Where did we decide that we were going to take this Hooks first approach?
Rachel Nabors:
"Where'd that come from? Does this reflect React blah, blah, blah." Well, I can tell you, we did a lot of research before figuring out how we were going to move forward with this. I reached out to people who are teaching React and people who are learning React and people who are using React every day.
Rachel Nabors:
And I did those user interviews, gathering that qualitative feedback. And what I heard over and over again was, "I'm teaching Hooks because all of those eco system is using Hooks and I can't even link to the docs because it's all classes. And then people get confused and I have to explain, and then they're scared." And it's like, "I see. So, we really need to be putting Hooks front and center. It's taking off."
Rachel Nabors:
We're not going to remove the classes documentation. But if everyone teaching React is teaching Hooks first, the docs should reflect that and assist those people spreading the goodness of React across the community. So, we make all these decisions based on research and community feedback.
Rachel Nabors:
We're not doing this in a vacuum somewhere. And I just want to say thank you to everyone who has participated in the research interviews and the surveys. And thank you also for clicking the thumbs up and thumbs down button.
Jamon Holmgren:
Even the thumbs down. Yeah, that's helpful.
Rachel Nabors:
They always help.
Harris Robin Kalash:
It's really funny you say that. What you mentioned happened today, I'm actually teaching React right now and, in the course, we go over Hooks, but the main point of Hooks ... sorry, not hooks. We go over classes, my bad. But we only go over it to tell the students that they're going to see it out in the wild and they should know about it and that we like glance over it and we focus on Hooks.
Harris Robin Kalash:
So, exactly that happens. But it's really good to see that all that is being thought of as well based on data, because I've also had experiences with libraries where they don't actually measure what people are teaching or using, and then they just switch everything. So, the new documentation become useless.
Rachel Nabors:
That is a big fear of ours. We don't want to have that situation happen. Can you imagine how much egg would be on our face? How embarrassing that would be? Like, "Oh, the React Core team released docs, nobody can learn anything from them." Eek. No, not going to do that. We're going to release things as well as we go along to get community feedback.
Rachel Nabors:
I'm always posting doodles for the different diagrams I'm working on to see if they resonate with the audience and if they're helping folks. Does it help you to see a diagram of the render and commit phases and practice? Does it help you to think of this?
Rachel Nabors:
Is React thinking about components right here? Is this a good visual diagram? So, it's an iterative process, but it also works as like a conversation with the community. And I look forward to rolling out more and more sample pieces of content as we move along.
Jamon Holmgren:
Twitter can be a good, tight feedback cycle for those types of things, right?
Robin Heinze:
So, if you want to have some maybe influence on the New React Docs, go follow Rachel on Twitter.
Jamon Holmgren:
That's true. Rachel, what is your Twitter handle for the audience?
Rachel Nabors:
It's Rachel Nabors. And it's the spelling of my name with the fewest possible letters. So, R-A-C-H-E-L, N-A-B-O-R-S.
Robin Heinze:
We'll make sure to put that in the show notes too.
Rachel Nabors:
Thank you.
Robin Heinze:
I have one question about accessibility. So, I'm curious what you're doing, what you've done in the past in the React Docs in the current iteration and what you're doing in this new rewrite to account for accessibility in its many forms, in terms of learning styles, in terms of language barriers, what kinds of things are you doing to account for that?
Rachel Nabors:
I thought you were actually talking about our accessibility section and I was going to be like, our accessibility section is not too bad. Okay. No, accessibility. Well, React is translated into multiple languages already, the documentation is. We want to get that far with React Native soon, too. But we're also transitioning to Docusaurus version two, so it's not the best time to kick off a translation process.
Rachel Nabors:
But for React, we already translated it to many different languages and the rewrite will mean that we will be coordinating with those teams around the world to ensure that the new docs are translated and shared in those native languages with other people. That is important to accessibility.
Rachel Nabors:
Not everybody reads things in English. Although, survey feedback indicates a lot of people do prefer to read it in English, but not everybody. And it's those people who don't that you got to accommodate. Also, it should be mentioned, the survey was in English. So, you might get some biased responses in there.
Jamon Holmgren:
Fair point.
Rachel Nabors:
True. But we did get some useful feedback about why people do and don't read in English versus their native language. And also notice that there's a discrepancy. We don't put the language front and center. It's like a hidden little button off to the side, and it might make more sense to showcase that more on the front page to make it more obvious the different languages that it's available in.
Rachel Nabors:
So, these are the sorts of things that we're learning about in terms of making sure that the information is accessible around the world. In terms of learning styles, we have had long thought and talk about that. As you know, big proponent of visual learning styles, while it doesn't make sense for us to create a full suite of videos for every single lesson, I would love to, I really would, but it does pose some challenges with production values, with captioning and translation.
Rachel Nabors:
It's kind of a big ask at this point, but it is something I'd love to put on the back burner to add videos. In the meantime, we have floated the idea of showcasing excellent community talks from people covering the same content and linking out to that on those pages to try to accommodate people who want to learn about this thing, but maybe by playing a little video while they eat their lunch.
Rachel Nabors:
Not that I do that. I do. And additionally, adding more graphics, like when someone's talking about a concept in front of the classroom, they should be able to just put an image up behind them while they're describing it that gives people the gist of what they're talking about.
Rachel Nabors:
How many times have I seen a slide like this? It's like every project needs a great logo so that when the person is talking about the thing, they can put the logo in the URL up instead of a screenshot of a GitHub page. Short story, go hire a logo designer from Fiverr or something. Your project deserves it.
Rachel Nabors:
And additionally, there's one more learning style that you don't see docs accommodating very often, but it's one of the most effective ways to teach. And I can say this because remember I said, I love to learn by pair programming. And this is the idea that you give people challenges and they complete them to proceed. Kind of like katas, I know Rust has its own little katas that you install.
Rachel Nabors:
So, we're considering doing something where we give people broken React code and initiate them into inspecting React using React dev tools and also using the linter to hunt down what the problem is and fix it, which would help reinforce lessons about how and when use effect is called right then and there.
Rachel Nabors:
Rather than people being surprised by this in the wild, not knowing, "I've got this problem, but I only know how to use console log. What's going on?" So, essentially teaching concepts while teaching people how to debug at the same time. And this really is a good way of teaching in the long term if you can incorporate it into your learning process.
Robin Heinze:
That's really, really cool.
Harris Robin Kalash:
Yeah, that is really cool. I'm curious, how would that be delivered? These katas? Would they be in the terminal or how exactly?
Rachel Nabors:
We're actually hoping to do embedded interactive examples right there on the page.
Harris Robin Kalash:
Nice.
Jamon Holmgren:
That'd be amazing.
Harris Robin Kalash:
That's awesome.
Robin Heinze:
Like little mini sandboxes, kind of?
Rachel Nabors:
Yeah. Sandboxes, just like that.
Harris Robin Kalash:
Awesome.
Jamon Holmgren:
What role do community tutorials and courses play in your strategy around documentation? And then a follow-up on that if you want to address, what role does something like Stack Overflow play in it?
Rachel Nabors:
The React Team has noticed a certain kind of question that crops up a lot. It's this question type that indicates that we haven't taught certain core things about how Hooks and function components work and how React works as a renderer. We've done a poor job of teaching them, not just to the community, but also to the people who teach the community.
Rachel Nabors:
I wish it were as easy as ... I learned React through community tutorials and videos and things. And even I will come into a discussion on how to document something and Dan will be like, "No, that's not how it works. It doesn't work that way, Rachel." And I'm like, "What? But that's how I was taught." And Dan's like, "We did a bad job of teaching people."
Rachel Nabors:
What we try to think of these docs as, it's not like we're going to be the thing that teaches everyone React. It's, we want to teach people how React really works so they can deeply grock it, so that they can build their own library on top of it. So that they can level up at work or so they can come in at work being like, "Yeah, the reason it's doing that is you haven't passed that as a dependency array to use effect."
Rachel Nabors:
These are important things and even experienced React masters sometimes lose out on these basics because they've been poorly communicated. So, we don't see the New React Docs as being like your one-stop shop to have a career in React.
Rachel Nabors:
We're not going to teach you Redux. Redux has its own docs, go read them. But we want to make sure that you have the core, the deep knowledge that the people on the React engineering team have.
Harris Robin Kalash:
That makes a lot of sense. And the quality of the blog posts are usually really good too. I've learned a lot just from those. Yeah.
Jamon Holmgren:
When is it not documentation that's the problem but rather the framework itself that's too hard to learn? Maybe for example, there's some concept that the core team has built, but teaching it becomes a real problem because the concept itself is just too complicated.
Rachel Nabors:
This is an interesting question that you've brought up where, interestingly enough, the best APIs are the ones that are written with a documentation person standing next to the API designer. There have been a number of APIs where I've turned to people after they've delivered it and been like, "Here, document."
Rachel Nabors:
I've been like, "Your getter and your setter are completely mismatched and they don't make sense with the legacy naming convention either. What happened?" But because the conversation, it got lost and the design proceeded and wasn't perhaps fully baked when people built it in terms of considering how it makes sense to somebody who's receiving the information with no context or not a lot or maybe with older context.
Rachel Nabors:
And there will be challenges, a lot of the core foundations in how React works. And they are deep functional programming concepts that the average web developer has probably only briefly encountered from time to time. But these things are not impossible to teach and they have been well thought out. I can assure you that React's API is no flippant thing.
Rachel Nabors:
The engineers who work on it, Sebastian, Mark Bode, Andrew, just the time and care that they put in to working on React core is quite astounding. I really do feel like I'm back working with the W3C where they're thinking very hard about the kinds of things they're putting out into the universe of tech and trying to make sure that they are good things that scale.
Rachel Nabors:
And they make sense in the long term. And that they never have to feel shame for having released something that did more harm than good. And while some of those concepts are going to be challenging to teach, they are not impossible to teach.
Robin Heinze:
Wow. That's really interesting.
Harris Robin Kalash:
Yeah.
Robin Heinze:
I'm wondering if you have any specific advice for many people who are probably listening who are working on a team and maybe they don't have a full-time dedicated documentation expert working with them. And they're having to write their documentation themselves in addition to building their product-
Jamon Holmgren:
Robin, are you asking us for a friend or is this you?
Robin Heinze:
Totally for a friend. Yeah. Any specific advice about what kinds of things make good documentation, how to balance trying to wear both hats?
Rachel Nabors:
First, make sure you're actually allowing yourself time for documentation. I can only tell you how many times somebody I'm working with is like, "Can you just spin this up? It should only take you half an hour. It would take me half an hour." I'm like, "Yeah. And what you create wouldn't be as good as what I'm going to create.
Rachel Nabors:
"It would take me half an hour to create this new piece of UI and you would tell me I did it wrong. I will do the same to you." So, just remember, there's a certain amount of respect that goes into this. You shouldn't be intimidated, but you also should approach the challenge with some amount of respect that it's not going to be easy. You will have to grow.
Rachel Nabors:
You probably want to pick up a book like word by word, or read a couple of articles about what makes good technical documentation. Or at least associate with the basic structure of an essay, which is intro, content, summary. Take a little bit of interest in how you structure the things coming out of your mouth or out of your hands. It's the same as structuring your code in many ways.
Rachel Nabors:
It's just, you're writing for the human API, not the one that lives on the computer. That said, I think the best thing is make sure you give yourself enough time, run your documentation, your initial passes. Pass somebody else, somebody who's just associated with it. Also run it past someone who knows it better than you are to make sure that you've captured it well.
Rachel Nabors:
You might be like, "I did not realize that that method did this thing. Okay. That is the more correct way to say that." And take notes as you go, you will learn that there's hidden tribal knowledge. Once again, always keep a cheat sheet around. And as that cheat sheet starts to flow over, codify some of that information and start sharing it with other people.
Rachel Nabors:
The sooner that you all start firing on the same cylinders, the more you start to wire together. And it's very good for the cohesion of the overall team. That is where I would suggest there's also this great community, Write the Docs, it's online. It's always publishing great blogs and articles. And I would recommend that you give it a check if you're curious about documentation.
Rachel Nabors:
And if you're thinking, "But I'm an engineer, Rachel. This isn't my job." Okay. I get it. I get it. It's not your job. I hate making banner ads too. But sometimes, you got to make a banner ad for a survey or something because you don't have a designer. But also, that's someone's job and take some pride into learning how to do this job well. Take some pride in it because now you're going to understand what goes into it.
Rachel Nabors:
And you're going to feel so grateful when somebody volunteers and says, "You know what? I love writing. I have a degree in English literature and I love to code and I would love to run your repos docs." And you're going to be like, "You are a magnificent beast and I'm sending you swag right now."
Rachel Nabors:
Because you'll have suffered and you'll understand. But also, it'll just change the way that you think about your APIs, about how you share information. It'll be really good for you. I promise.
Robin Heinze:
So, basically treat your documentation like it's a full-fledged feature and not an afterthought.
Rachel Nabors:
If you care about scaling and you care about ... let's see, what did I say? I just said this on Twitter. It's like-
Jamon Holmgren:
I saw this tweet. Yeah, I saw this tweet, it was very good.
Rachel Nabors:
I'm going to do the thing where I go to Twitter and read what I have. I said, if adoption and/or scaling are important to your project, then documentation is also important. Now, there are projects where adoption and scaling are not important. I have a little project on GitHub that's just like a little digital art anthology. I'm the only contributor. I don't want your PRs.
Rachel Nabors:
Thank you. You can take them right back. I'm not going to document anything in there because it all lives in my head. And if it's just two of you doing a project for like, I don't know, a conference or making a little page to collect sign-ups, you don't need to document anything there. You don't need it on a contribution read me.
Rachel Nabors:
However, if you do care about adoption, if you do care about scaling a team who can work on it, you will want to think about documentation very early. Because you're investing in how quickly you can ramp other people up. You're investing in how far and how fast your knowledge can travel.
Rachel Nabors:
And if you don't invest in that early, you're putting this huge barrier to entry. Like, must read through X amount of source code to understand. And that does privilege certain people, but it also can inhibit the spread of information. If that's priority for you, you might want to get on that.
Jamon Holmgren:
Yeah, I ran into a situation where one of the projects that I maintained was not really getting ... We were getting a lot of issues, but we weren't getting a lot of pull requests, not a lot of contributions. And to me, that was an indication that we needed more documentation around the contributing side of it. Like, what do we even do here? It actually led to a rewrite of some of the internals just to make them more easily understandable to contributors.
Jamon Holmgren:
But also, I wrote a lot more documentation for, hey, if you want to contribute, here's some just basic things about where are things? How would you go about this? How do you even create a PR? Because some people, this may be their first time contributing to open source. And after I did that, we got a lot more contributions. It was a really awesome feedback loop there.
Rachel Nabors:
And even experts need those guides. When I first landed on the React Native site, I was like, "Oh gosh, I have to do a pull request. What's this Docusaurus thing?" And in the read me, it stepped through how to get it running on my computer. And I was able to make my first PR within a few minutes of spotting what I needed to do. It's important.
Rachel Nabors:
It just makes it faster for people if you don't expect them to immediately know. And actually, this has brought up something I want to mention here because a lot of people, they love React, they love React Native, and they're like, "How can I help? I want to help. I want to contribute. Can I write your docs? If I can't write source code, can I write the docs?"
Rachel Nabors:
And that's a great attitude. And with React Native, when we updated the documentation earlier this year, and we did the big component drive where we were adding in line examples that were interactive for every one of the components and APIs, that was so great. That was wonderful. But not every project has an immediate need for that or an immediate need for translations.
Rachel Nabors:
There's not always a way that you can put hands on the thing that you love. Like the React Documentation right now is largely something we're building privately and we'll start sharing more as we go, because it's more like a curriculum than a group effort. And that requires a little bit different process.
Rachel Nabors:
But I want you to think about if you're getting really fired up about contributing to open source being packed over and thinking about documentation, what other projects do you love and you're passionate about that maybe don't have great onboarding for contributors? Or maybe their API docs are a little out of date or confusingly written or, oh my gosh, they don't have a style guide and all these pages sound like they were written by different people.
Rachel Nabors:
This is a great opportunity for you to step in and get active and involved. You may not be helping out React and React Native specifically, but you'll be engaged with the community. There's always a repo manager out there somewhere who really wants your help.
Harris Robin Kalash:
Speaking of that, I guess, how important is it that a person ... for high quality docs, how important is it that the person writing the documentation is close to the engineering team? And does that person necessarily have to be technical? Can I outsource it if I'm a busy startup?
Rachel Nabors:
That's a good question. Oh my. Well, I think it depends on exactly what you're trying to document there. I have met many technical writers and I got to tell you, they all, at one point in their life did time as engineers. Maybe they didn't want to be engineers until they died, or maybe they experienced many career interruptions that prevented them from being like a 10X engineer early in their career.
Rachel Nabors:
But they're still a good engineer and they're very good at communicating. So, they teach engineers now. There are many ways that people end up as technical writers, but having an engineering background does help or at least being a person who's like, "I'm doing tutorials on the weekend to figure out how this works. Yeah, now I'm going to write my own."
Rachel Nabors:
You can't have someone write a tutorial about how something works if they never open a terminal. They got to do it. Not just anybody can come in. However, if let's say you have a bunch of technical writers, maybe English is a second language for them, they've been contributing and you've got all these docs.
Rachel Nabors:
You might then consider hiring an editor or proofreader who has English literature background or has done editing professionally. You can even pay people to do this, there are professional ones, to go through and proofread all the documentation. Ensure that the tone and voice are being used correctly. Like, if it's switching between I, me, you, they all the time, that can be really confusing.
Rachel Nabors:
You want to just stick to one model that refers to the author and the audience. And they can go through and correct all the language issues, they can harmonize the voice and tone. They can make sure that every menu opening instructions are consistent. Oh my God, the menu opening instructions are all over the place in these things.
Jamon Holmgren:
But what do you mean by that? I'm really curious.
Rachel Nabors:
All right. In Chrome dev tools, open terminal. Okay? There's like a bajillion different ways you can say that. You can list out the hot keys. You could have a little bolded file list with carrots going to like, here's how you open it from preferences. And then you need a different one for Mac and a different one for Windows. And they'll be all over the place, these different ways to get to different things.
Rachel Nabors:
They come in so many varieties and you want to stick to one. So, a proofreader or an editor can go through and do those things and be immensely valuable to a project on their own. So, you might have an engineer writing tutorials who's just like, "I've just got to get this out. I got to move on."
Rachel Nabors:
And then you might hand that off to somebody who doesn't open a terminal to go through and ensure is grammatically correct, proper English conforming, et cetera. And you might think, "Well, is that really necessary?" Yes, it is. When people are running things through automatic translators like Google Translate, if it's not grammatically correct English, those translations can be completely botched.
Rachel Nabors:
Correct English, grammatically formal, correct English just parses better, both from human to human, across cultures and from machine to human. So, keep that in mind. It's a feature. So, to answer your question, yeah, people who don't write code can be a part of the documentation process.
Harris Robin Kalash:
Got you. Thank you. That was very insightful.
Jamon Holmgren:
What are the React Native specific challenges? For example, native code documentation, working with Xcode, working with Android Studio, all of the things. Because as you mentioned before, React Native is quite a bit more complex than React itself.
Rachel Nabors:
Yeah. This is one of the reasons why community contributions for React Native make such a huge difference. With so many different platforms, things are changing all the time. Like new version of Xcode comes out and the way that you inspect things completely changes. Now we've got web audiences. I think it's something like split three ways.
Rachel Nabors:
We've got about like 30% of people come in with no ... React Native is their first programming experience. And the other 70% of people have a mix of web, Android and iOS backgrounds. Originally, the docs were written like, "So, you know about React JS? React Native is like React for native development." And it was like, whoa. First off, Android and iOS developers don't like being lumped under the term native.
Rachel Nabors:
And seriously, you're an Android developer, you're an iOS developer. We're not second-class citizen. Have you seen my market share? So, you have to be respectful. And we started changing how the docs just refer to the people who use the docs. We've started adding little call-outs like, "If you're familiar with web development, this is like a design system which speak directly to those audiences and people with those backgrounds."
Rachel Nabors:
But once again, we really rely on the open source contributions of Android, of iOS developers coming in and being like, "Process is updated, getting started. Doc is out of date. Here's a quick fix. Peace." And then just appear. It's like, "Thank you. Thank you. I do not test this process every morning. I would not have updated that without you. Thank you. Thank you so much."
Robin Heinze:
That's really interesting. I'd never thought about how iOS and Android developers wouldn't want to be lumped together. That's really interesting.
Rachel Nabors:
We all identify with our own tribes online. You got to be respectful of that.
Jamon Holmgren:
I think that one of the things that the React Native community could do a better job of is reaching out to iOS and Android developers in general. I think that the React Native community has a natural onboarding, as you mentioned, Rachel, from web to React Native. You already know React and you can move right into that. At Infinite Red, we actually came from the native site.
Jamon Holmgren:
Although we had done web as well, we had a website, but we were doing iOS and some Android development as well. And for us, moving into React Native was fine. We understood the concept of cross platform development. But I feel like, like when I talk to iOS and Android engineers, now you've got me thinking about not saying native. I actually appreciate that.
Jamon Holmgren:
But when I talked to them, I say, "We, as a community, React Native community, need you. We need more iOS and Android developers to be in our community to give that perspective of not being afraid to drop down into the native layer, if it makes sense.
Jamon Holmgren:
Being able to not just copy and paste stuff from Stack Overflow, but actually really understand the native underpinnings of all of these systems that we're using." The website of things is great. And it's a very awesome onboarding and it makes mobile development in general accessible to a huge number of people that maybe otherwise wouldn't be able to do it.
Jamon Holmgren:
But I just like to tell people, like, "If you're a native developer, if you're an iOS or Android developer and you have that background, we need you in the React Native community."
Rachel Nabors:
I feel like these engineers might not realize that they are a channeling of this knowledge into their community. When I was doing research on the React Native community and how React Native teams are built, it's usually a handful of React Native engineers and one or two keystone iOS or Android engineers. And those engineers are the ones who come over and do the pair coding.
Rachel Nabors:
And they're like, "We need to build out this module. And I'm keeping track of how this platform is changing. Now we need to update that process." And they channel their knowledge through the other engineers. This is actually kind of brilliant natural mentorship. It's a position, I think, of great value.
Rachel Nabors:
If you want to be valued on a team, if you want to really bring a lot to a company or a project, I feel like React Native teams are one of the places where you can have that impact as an iOS or an Android engineer. You will be able to be such a force multiplier, like you might not be on other teams.
Rachel Nabors:
And when you bring that to the community, when you contribute your knowledge back and spread it by documentation or building tutorials, or just sharing with your team, it's great for the React Native community. It goes so far.
Jamon Holmgren:
I just have one more question for you, Rachel. What sucks about the React Native Documentation right now?
Rachel Nabors:
That it's not automated. That we do everything by hand. You always run into this weird dichotomy of when docs are generated automatically, then you have to write them in the source code. And the problem with writing things in the source code is sometimes engineers want to get something out fast and they just write, go beep boop, and don't fill it out.
Rachel Nabors:
And the docs are then useless. But then doing everything by hand is labor intensive. And you need to find this sweet spot between where things are automatically generated, but people can still contribute and improve what exists. And that is the current challenge, I think, facing the documentation for React Native. We also need a tutorial, but I have somebody working on that.
Rachel Nabors:
Thank you. So, we're always working and improving things. But I saw what a difference making sure that these many surfaces were up to date at all times made in people's happiness with the docs and their satisfaction with the library. And it's a problem that so many different projects face. If there was an easy answer, it would exist by now. But I really think that it's an answer worth pursuing, especially for React Native.
Jamon Holmgren:
Well, thank you so much for dropping all that knowledge, Rachel. We'll have to have you on again, maybe after you've done your huge project, your big initiative, switching things over to the new, more Hooks centric documentation. Before we go, I want to ask everybody, if anybody has a weird bug.
Jamon Holmgren:
We do this weird bugs section of the podcast and I always look forward to it because there are, as everybody knows, who does coding, sometimes you run up against weird bugs that you just have no idea what's going on and it takes quite a bit to get through them. Anybody seen a weird bug in the wild?
Robin Heinze:
Yeah. So just this week another developer on my team was banging his head against this issue for over a day, which was that he was using MobX State Tree and he had a use effect hook on one of his screens and it wasn't triggering when he made changes.
Robin Heinze:
It turns out he was observing an array of MobX State Tree observable array and use effect doesn't trigger when you change contents within the array because the array itself has not changed. And so, it turns out you need to basically convert it to a JavaScript array and you can do that by calling slice on your observable array. And then that way React will know that it changed and will run your effect.
Jamon Holmgren:
I've seen that happen far too many times where ... and I think this goes back to what Rachel was talking about, where sometimes just not really understanding the internals of how React is observing this in the use effect dependencies, if you pass in an array, but the reference to the array never changes, then it's not going to know that anything has changed.
Jamon Holmgren:
Even though the internals of this observable array are changing all the time and this effect needs to be run. Yeah, that's an interesting one. I helped Robin and Mark, our other developer work through this. It wasn't immediately obvious why it wasn't triggering, but once we got a chance to play around with it a bit and added that dot slice method to it, then it started working again. And Mark was so happy.
Robin Heinze:
That's a great example of having to marry documentation from the various tools that you're using. You have the React Docs, but the React Docs alone wouldn't have told you what you needed to know about observable arrays from MobX. And so, having these documentation sources and having to work with them together is an interesting challenge for us engineers.
Jamon Holmgren:
For sure. Very cool. Well, thank you all. A huge, huge thank you to Rachel, of course, for joining us today. And just so much knowledge, I feel like there were many questions we couldn't get to in this episode, but we'll save them for next time. Of course, our episode was brought to you by Infinite Red. Just check us out at infinite.red. Rachel, where can people find you again on Twitter?
Rachel Nabors:
You can find me on Twitter at Rachel Nabors. That is a N-A-B-O-R-S, like next door neighbors, but with fewer vowels and consonants.
Jamon Holmgren:
Perfect. And Harris, where do people find you?
Harris Robin Kalash:
Brunostmann on Twitter. So, at B-R-U-N-O-S-T-M-A-N-N.
Jamon Holmgren:
And Robin, where are you on Twitter?
Robin Heinze:
I'm @Robin_Heinze, and that's with an E on the end.
Jamon Holmgren:
And I'm Jamon Holmgren, J-A-M-O-N, H-O-L-M-G-R-E-N. And you can subscribe to our podcast to get future episodes on all the major podcasting platforms. Just look for React Native Radio. Thanks everybody for listening and see you next time. Thank you very much.
Rachel Nabors:
Thanks for having me.
Robin Heinze:
See you everyone.
Harris Robin Kalash:
Thank you. See you.