 So, hello everyone, today I'm going to talk about writing docs and in particular how writing docs may let us not only contribute to the project that we're writing docs for but also it can be a great opportunity for you to learn about the project and if not advancing your seniority as a developer. My name is Wei, I work at Sharpie which is an e-commerce platform here in Singapore. Our team is with the React ecosystem now but I prefer to identify myself as a web developer in general. The story I'm sharing today is not as exciting as shipping to a billion people but it's about writing docs for a couple of projects throughout the past year and hopefully I can share something you can use on your own. So because I'm also talking about learning today, I want to first give you a bit more context about where I am with respect to my own career. So I've recently passed my fourth year as a front-end developer so I can say I'm probably not a junior developer anymore but I'm also not one of those who are super talented but perhaps that makes me a better person to talk about learning because I know exactly how I got better. In my first year, I enjoyed the job as if I was playing Lego, it's like assembling pages from PRD, API documentations and design specs, it was very playful and I had a lot of fun. I joined my current team in the second year where nearly all my teammates had a CS degree and they were good to the level I could not evaluate myself so it was like meeting my peers of my major but feeling a bit under qualified. And then in my third year I got a little lost in building features, I built a lot of features but only features. So having in mind to gain some more inspirations about what other developers are doing in this world, I was looking for a conference to go. So I ended up going to Ria Rally where I learned about this project to write docs for Ria Redux which I'll talk a little about today. Then in my fourth year, I spent a lot of time organizing a podium for my team where we talk about things we found interesting as a React developer. I myself gave a lot of talks there as well and I said that speaking and writing, they share a lot of spirits in teaching and by teaching you'll gain a better understanding. So the bulls have been a significant boost to my learning and writing in particular is my favorite and is what I'm sharing with you today. And speaking of RK, since we're here in Singapore and we're at junior depth today, I think it's also a great context for me to tell you a little bit more about RIA knowledgeable. This podium is now also publicly run as a meetup. It happens the first or second Thursday of every month and the spirit of RK is that when you learn something, the best way for you to learn it is to teach it to someone else. So Inel has a very small core consisting of a few very cool React developer, I believe. And last month, we talked about binary heap which is an implementation optimization for React's scheduler. And then last month, we had a developer who talked about dancing. She built a little dancer with React hooks and the time she talked about this, we were live tweeting it and Dan Abramov saw it and he hit liked and so that was like the React core team is looking at us, this thing cannot be bad. So that's a little bit sorry about RK. So today I'd like to first talk about what I am learning by writing docs and why it's such a powerful tool in learning. And then I'd like to talk about the most critical challenges of writing docs for myself, namely it is about understanding and explaining complex technical concepts. We'll talk about how we can integrate some of the practices we can do on a daily basis. And then I'd like to talk a little bit about the value of how docs contributions can be a unique chance to create great impact. And then finally, I want to share with you a few tips that I picked up and can get to start it and get to practicing. So let's go back to a day of React Rally 2018. It was my first conference trip. I was very shy and I didn't speak to a lot of developers at all. And it was the day after the conference, I was sitting at a table where a group of developers and speakers, it was very relaxing because the conference was over and they would have some casual conversation. And that's where I met Mark. He is a maintainer of Redux. He was also there. And at some point of time, he mentioned that he was looking for people to work on the project to rewrite docs for Redux and React Redux. And that's if people were interested to help. What would your answer be? I normally would have a yes or no answer to things I'd like to do or not. But this time, it wasn't that clear for me because I was apparently attempted, but I also felt more uncertain about how much I could actually do. Am I senior enough to write documentations for such a popular project? And do I know much enough about Redux or React Redux in order to write a complete set of documentations? And writing is hard. I think I am a person, like words aren't really my thing. I was more comfortable writing JavaScript than coming up with human words. And not to mention that I'm actually a non-native speaker of English. I constantly struggle with grammar, and I find it really hard having to explain technical terms in English as a second language. But maybe it's because I kept wondering about all of those questions. It's like, can I do this or not? And on the other side, you actually have this chance to pick this up. So after two weeks, I was back home. And I reached out again. And Mark, in fact, had already had the projects planned out in two GitHub issues where he listed out the outline of the docs and the topics he wanted to cover, how to organize them. And he also included a list of resources we can use as reference. So I picked Redux because it seemed a bit easier. And I did the simplest thing you do in college when you study, for example. I read everything. And it was also the moment when I scared myself by realizing that I do not really know Redux. In case you're not familiar with Redux or maybe you're not with the ecosystem, let me quickly walk you through and overview what it looks like. So Redux is a state management library that maintains all the data of your app in a big object, commonly referred to as a store, and you reduce the store states by dispatching actions. And then you provide the reducer functions, which specify how your store should update according to those actions. And then Redux is then the connector to make your app work with Redux. So with a lot of details omitted, here's what your code would roughly look like. You create the store with Redux, and then you provide that store in your app room. Then you can write your components as if they already have the data they need from the store, but they don't until you connect them to the store. There are two tongue-twisting functions that are related. One for you to get the data from the store. The other one for you to dispatch actions from the store. What I want to tell you about here is that you can see that the APIs are very declarative. You call connect, and you supply the state and then the dispatch, and then you call it again with your component. They do exactly what they do. So I've had no trouble writing code like this since day one when I copy the code from somebody else. And for two years, I never really bothered to care for what was really going on under the hood. Now, it seems to me that this is the perfect example of me knowing the name of something without knowing it at all. Anybody know Dr. Richard Feynman? He's a, I see a few hand-living here. He's a physics professor, a Nobel Laureate, and his action notes were actually what helped me pass my college physics courses. And so people also collected some of his lectures into a few essays, books of essays. And in one of the books called The Pleasure of Finding Things Out, and in one of the chapters Feynman mentions that when he was a kid, his father has once told him about the kind of bird. He told him the name of the bird. And in fact, he told him the names of the bird in multiple languages. And then he showed him that that is not the same as knowing what the bird is. You can know all the names of the bird in all the languages in this world without understanding what this bird is at all. Isn't this exactly the same as us knowing how to call a function but without understanding the API at all? This scares me to be honest, because nowadays our libraries and toolings are built towards better developer experience. They encapsulate all the heavy liftings inside the library so that we don't have to worry about them. I think it's a good thing most of the time. We can happily build our features and maybe go home early every day. Have you noticed the fact that now we can actually get away with doing our job quite all right without understanding anything about the underlying structures at all? So as a developer, if our day-to-day job does not require that we understand the library we use or the under-the-hood implementations, when and where do we learn about them? While we're clocking in a lot of features and implementations, when is our chance to go into the other direction to go deep into our understanding about our field? So let's consider an example. For those of you who use React Redux, have you ever wondered when will MapState to props functions run? So it turns out that whenever our store state changes, each of the connected components will have to figure out whether the part of the data they need have updated or not. So they all will run their MapState to props functions if you've never wondered about that. So since our pages may not contain just one or two connected components, in fact, sometimes we can have a lot of them on a single page, that means our MapState to props function better be very fast. It better be as fast as possible. Maybe we should memoize them if needed. And no asynchronous calls. Plus, they should probably return only the relevant data that is connected components care about, because it matters to whether their components will call their render functions or not. So as a college math major, I've learned a lot of obscure facts that aren't really useful to my career as a developer. But this time, however, I think for the first time, I became the person in my team who seems to understand why 120 item cards were calling their render functions whenever the user clicks login. It's an action that is completely irrelevant with item cards. So whether the excessive renderings or excessive rendering calls are causing performance issue or not, that is another question. But have you noticed that this is probably some under the hood mechanisms that we should at least understand? And we are not getting told by only knowing the names of the function. So that had a subtle impact in me. I became slightly more confident and much more interested in all the things about React Redux. So let's pause here a little bit. I think I wouldn't have done my talk if I do not tell you how exactly the learning happened. And you may have heard the suggestions from a lot of senior developers who encourage you to work on documentations. But they may not have time to justify the reasons for you. And in fact, I am giving the suggestion for our new joiners now. And today it comes my chance to elaborate. So first, Redux provides you a ground for thorough research. If we are only to, for example, figure out a problem, we encountered the other day, chances are our learning would end at the point where our problem is resolved. Now, since we're working on documentations, I would say that this is the exact situation where we should go in full capacity to learn about everything we can about the subject. For React Redux in particular, Mark has a red poll containing a handful of good links in the subject. Before I was writing the docs, I've read maybe one or two of those. As I was doing the research for the documentations, I tried to read as many as possible from that red poll. And actually soon enough, a lot of the plot polls are saying roughly the same idea over and over again. And that is when you know that you're reading the kind of material that everybody is saying about React Redux. And here's our favorite physics professor again. So Feynman has been advocating a method called the Feynman technique. Namely, when you learn a subject, after you pick the subject, what you do is you teach it to a toddler. And then in the third step, you find the gaps within your understanding. And then finally, you refine and simplify your language. And then you repeat, you do this over and over again. So writing docs for me is like this process going over and over again until our documentations are well written. And if we are writing a doc for popular open source projects, people will come and review our work. Not just to fix our typos or mistakes, and not only normal users. In fact, domain experts, maintainers, the people who created the libraries, they will come review our work. Because they care about how the community is understanding the libraries. They care about what we teach to newcomers. And they care about what is being said on the official documentations. But then for us, junior developers, right, or someone who is learning a new library, isn't this the best mentoring we can get? So the day that my first piece of doc was merged, I thought everyone should be doing this, right? But no, very few people are doing it. Well, I think these are something I figure out over the years. I think it is indeed very, it takes a lot of time and commitment. It might not take you too much time to fix typos or add some minor information to the docs. But writing more complete set of docs, it takes a lot of time and commitment and collaboration with the maintainers. Maybe multiple rounds of revisions on the draft if the maintainers will help you. And then we all know that writing is frustratingly hard. Even Pulitzer winning authors will tell you that writing is hard. It's hard for everybody. It's just that we have different takes on the challenges and different ways to tackle it. And then I think for me, the challenges are centered around understanding and explaining complex technical terms. We're talking about writing projects that we didn't write ourselves. Although I think even for projects that we do write and maintain ourselves, we still need to understand the actual use cases, which are equivalently, if not more challenging, and both situations we need to explain them in human languages. So this brings us to the second part of my talk. Let's now take the challenges as a given and see how we can get better at them. So it turns out that I think understanding and explaining a complex technical ideas, these are two sides of the same problem. I haven't come up with a name for that problem yet, but maybe I will sometime later. But what I want to tell you is I feel they go hand in hand. They help each other. Don't be too certain that you understand something until you can explain it to another person. And after you've done it, you've done explaining it to another person. Maybe after you've done it for so many times, you'll get a refined understanding of the subject. So throughout the past year, I've been picking up on little techniques here and there on a very small scales, but on a very regular basis. That allows me to practice those two together and hopefully, getting me towards becoming a better developer. So let me ask you this. What do you do when you have read an interesting technical article? Or maybe you have watched a good talk? Or maybe you've run into a problem and you're Googling it and you've found the solutions to a problem you're tackling with in a GitHub issue. So try this. If you've read something valuable, this applies to not just one of those, but most content that you consume. Don't just stop bookmarking it. Instead, try to summarize the content in a few words of your own and share it with someone else. I think it works best if you have a coding partner who you can conduct one-to-one sharing with on a regular basis. For me, what happens is more often than not, the first time I explain it, it always goes worse than what was in my brain. So I also often realize that I'm missing point from here and there on the spot, it doesn't feel great. But it tells me where my mind gaps were very effectively. So one-to-one sharing is something that I currently have the luxury to exercise with because recently I have a very great coding partner, also a great mentor who we spend like half an hour every day and we talk about what our progresses were for the past day. And I'll take this chance to explain to him what problems I have solved and step by step how I managed to solve this. And I also get to define the problems to the person so that I can verify whether he is getting my explanation or not. And if you do not have a regular coding partner, there are still some other choices you can go with. You can tweet it and once again, don't just retweet it. Put a few lines of summaries that your readers can have a heads up of its key points and if you've landed there because you're solving a problem in your code then just don't just toss back the link. Write a few lines of explanations such that the people who need to understand the situation can save some time. And then create a short note section in your writing. The key is to try to fit this into a regular routine if not a daily routine. So if you're doing the short note thing on your block, make the layout of your block make sense for smaller notes. Don't block yourself with really long block posts that you can't finish in like two weeks, do this on smaller scale. Small block posts that you can finish within maybe a reasonable like a half an hour of a time. If you do this as a daily exercise, chances are you'll have clusters of those little notes and maybe in two weeks, you can write a longer post that connect all those smaller notes that become a better idea of a block post. So coming back to docs, how does writing smaller notes help you with writing docs, right? So this can apply to the docs you write when you try to understand the source code for each part of your source code. You can just put out a few lines describing what this part of the program is doing. And then before long, you'll have a bunch of those notes like these and there are good grounds for you to start writing the documentation so that when you actually start, you won't have like a blank page. Then I want to give you an example of what I mean by being intuitive rather than imperative. So for me, docs is something that connect the language that a machine can understand with a language that human beings can understand. So the example is factorial function that we all kind of know from high school. So a factorial function is a function where you take an integer n and you multiply that n with n minus 1 until 1. It is also a relatively expensive to compute function so we will memorize them. So this is the function that we write. But for today's context, let's look at the comments. So the first version of this comment is very imperative. It nearly says exactly what the code is saying. So on the first line, it says create cache if there is none and then you read the actual code. Because if factorial cache is non-existent or falsely, then factorial cache is you set that to an empty object. And then on the second, wait, oops, sorry, my... And then on the second comment is saying if n is in cache, then return it. And then the code is saying the exact same thing. So I'm going to read the third and the fourth line because they're all very... They're all just the sounding board of what the code is doing. Let's try another one. So try to read this as a user. As a reader to begin with, you read initialized cache. And in your brain, you'll comprehend that the task that we're doing is to initialize. And you will actually know what you want to do when you initialize something. And then we say short circuit. And now you know that what we're doing here is to return early. And then on the actual computation step, it first tells us what the definition is, hinting to us that we can treat that as a given. And then it tells us that it is possible to recursively compute factorials with existing results by doing this. And then if we understand the definition of the factorial, this should not be too hard to understand. And then it tells us about the initial case, which is what we do when we write a recursive function. And then eventually it tells us that we're going... In order to reduce computations, we're caching them. And then before it returns, it tells us why we're guaranteed for a return. So I think the trick is to always look at the intention and the motivations of the thing you're trying to explain. And if people understand your intention and motivation, they can plan out the imperative step by themselves. And even if they do not yet know what the imperative steps are, they can probably read your code and understand what exactly you're doing. And then the same drill applies to docs writing. This is my magic line. The goal of this piece of doc is to do this. Whenever I work on docs, I always put this line on the first line. You don't have to think it's permanent. You're free to remove this once you are done. But for me, it serves two purposes. One, it gives me a lead in my thoughts, because I know what exactly I want to achieve with this little piece of doc. And then two, it starts conversation mode. So once I say this line, the goal of this piece of doc is to do this, it feels like I'm starting to talk to somebody. So that makes the language more natural. If we're starting with something more like speaking to a machine, and that will get us really nervous and cannot write something very eloquently. How many of us here are non-native speakers of English? Oh wow, that's a lot. Well, regarding this topic, I want to first let you know that there are more people on the web who can fix your grammar issues than those who will take the non-trivial efforts to write documentations. So please don't let this restrict you before you even start trying. And then I have a short list of tips. Improving English is a huge topic that I cannot finish within the given block of time. So please allow me to be brief about this, and only share a very few things I repeatedly do as I write the docs. So the first one is to make use of the source. It's a cheating trick. So if you YouTube search this, there will be videos teaching you how to find the source, and there are videos saying why you shouldn't do this. But I am very beginner to English, so it works well for me. And the reason is it is harder to come up with words than to pick from a list of words. So most of the dictionaries that we have even allows us to recursively try to find our terms. And then here we are looking for sources for cool. And then I think we find elegant, I believe. And then in elegant there is another term that says neat. And then once we go in, oh wait, ingenious, sorry. And then there is actually an example saying, an example of ingenious that's like an ingenious software solution. So it's a cheating trick. Let's see, do I have my notes? So the next one is proofreading. I think most grammar issues can be resolved by proofreading. Namely, what you do is, what works for me is I connect multiple times of proofreadings. And for every single time I target only one type of errors. Because all of those are really very objective, so you can't miss them. You can just go for one proofreading of your work, just go in for typos. And then another time you can just go for punctuations. You have one single task in your mind and then you can, it's only, so for the list here it's only five times. And I don't know if you will think this is a lot, but for me reading the piece five times is still taking a lot less time than writing the piece. So that works really well for me. And I have a very short list of books that I read in order to improve my writing. Nicely said is a book on writing styles in our industry. It is a thorough intro to proper writing styles for the internet context. It's very fast and lightweight. So I think it's good to get it started. And then on writing well it's like more classy look on writing in general. Slightly opinionated, it's worth, but it's also, but it's very amusing to read. So it's highly recommended. And then Go Pro's is a personal favorite. It's written by a pleaser winning author together with his editor. It's not as relevant as the first two, but it's very beautifully written. It's very insightful. So if you want to go deeper into writing you can read that one. And then the fourth one is like the classic English text. So after a few months, Mark asks again for help on re-reduced docs. And he asked for an FAQ entry to explain some differences and comparisons between using Context and Redux. I actually had a eureka moment when I collected all the materials. I read up on the Context a few links. Once again he had all those planned out. And came up with a take on the issue until eventually writing everything down that fits the context of an official documentation. Everything felt nearly natural. So this was me. And then in case you need a little bit of more motivations, you may wonder if something is already talked about in multiple places. It may seem redundant for you to say that again in official docs. But chances are if something is already said multiple times elsewhere, it may exactly because it is both important and not addressed in the docs. So official docs has this unique place that it will likely be visited prior to other resources. And what's more important is that people will treat it as more sound than others. So if something that people are looking for is already in the official docs, they don't have to look elsewhere. So it saves their time. It will in turn save more time because the questions won't even to be written. And that's one fewer confusion by the whole community. And that's collectively better understanding and it's very powerful. So finally I want to share a few tips along the line. The first thing is to find docs that is suitable for yourself. It's easy to drift off. In fact, it's actually very common to drift off because writing is once again very hard. So there can be some projects that are easier than others for you to work on it. So I think it is necessary for you to work on projects that you yourself are actively using. And also try to find the projects that are actively maintained and the maintainers provide guidance on docs contributions. So I've listed actually in preparation for this talk. Originally it was a slide in my slides. And I think it would be a better idea if I collect these into a GitHub repo so that people can also pull requests. It's Hacktoberfest for requests to add the projects that you find are worse. Writing docs for things that you can learn something about. So feel free to request this repo. And then if you can find some tasks from your work related with the project that you are working on for docs or vice versa, your work tasks use something that is looking for docs contributions. I strongly urge you to do so because it benefits many parties. You can contribute to the project of the open source project. This is very rare. And then for you you will be directly speaking to the maintainers. This means that if you have any questions as you work on your work tasks you have close access to official help. Then it should not surprise you that the maintainers actually care about your use cases. Especially if they are developing new APIs and are looking for early adopters be that early adopter. And your feedback may be adopted and that makes you not only a follower but a creator of our future. And all in all it benefits you because you'll be the expert in this subject matter in your team. And I think that speaks about your seniority way more convincing than the time you spend in the company. Will your docs contributions always get merged? No. In fact a lot of docs PRs don't get merged. I have like a ton of PRs that never get merged or are merged like half a year later. So here are my takes. If you've taken your own notes or if you've built a demo and it doesn't take you much effort to PR this in then simply create a PR and see what we get from there. For projects that are maintained I think it is critical that you take inputs from the maintainers. I think official docs is a place where you should prioritize what the maintainers have to say over your own because the maintainers have probably seen more users than you have. And there are reasons why maintainers want certain things to be taught in certain ways. So this is a place where we should follow the advice from maintainers. Sometimes even if the maintainers didn't provide two specific requirements it doesn't mean whatever we write will be agreed upon. So in this case it is to our interest to ask in advance for maintainers inputs and the more effectively our questions can reflect the thoughts from the library maintainers the more likely our work can get merged. Well, next time when someone look for Doc contributors will this be you. So that is the end of my talk.