The Treasure in Writing Docs

A True Gem in My Learning Folio as a Work in Progress Web Developer

How much do you think you will learn by writing docs? You pick up a topic, read the relevant code, blog posts, answered questions, and organize them into the context of official docs. The magic lies in the role shift from a developer to an explainer, and an end user to a maintainer.

The mission to explain things to others makes your learning more interactive, and the top-down approach to the subject matter nurtures your curiosity to go deeper. What's more, the collective knowledge on the internet becomes *your* knowledge, the answers to questions no longer scattered everywhere but live organized in the official docs, thanks to *your contribution*.

It's probably the best #learnInPublic habit that too few people know about. It's a true gem I keep in my learning folio, would you like to carve yours as well?


This page is playable as slides!

Press p to play as slides, then j and k to page.

Hello, JSConfChina Day #2 :)

Hello everyone!

reserved slide to talk about yesterday

how has day 1 been for everybody?

for me, I learned that TypeScript can help us write JavaScript that is scalable and type-safe, I also learned a little bit about PWAs, that they're not just the little dinosaurs, and we're not just there to make the lighthouse happy, but we have a set of powerful toolings to help us profile our app and build sensible UIs.

For the remaining of the afternoon I was basically dreading about my talk today. But I came back for the panelist discussion. We talked a lot about TypeScript, how we all believe it's useful but it's hard to quantify. Then we talked a lot about GraphQL, we shared about the toolings we use - although we don't have SWAGGER, we have iGraphQL. And then speaking of optimization, I believe I heard caching at least twice. I missed the serverless talk which I'll definitely watch the video once it's out, but I learned the practices that Alibaba takes to differentiate their environments - by using a centralized service that will tell you which environment it is by IP address. So that was quite interesting. I'm very looking forward to the panelist discussion today.

So, that was my recap for yesterday, what did you learn? If I run into you today here and there I might want to hear about that.

Learn as I Write the Docs

Okay, let us tend to my topic now.

Today I'm talking about writing docs, and in particular, how writing docs can not only be a contribution to the project, but also a great opportunity for you to learn about the subject matter.

Now, can we have a show of hands how many of us self identify as a junior developer?

[WiP] Web Developer / Wei / 皋玮 / @wgao19 everywhere

I cannot be junior forever, but I kind of self identify as a work in progress web developer, meaning I enjoy the process of getting better.

PNG image CA4C2081B96E 1
PNG image CA4C2081B96E 1

My Chinese name is 皋玮, I go by Wei as well in case you don't speak Chinese. I work at Shopee. We are an e-commerce platform based in Singapore serving 7 countries and regions in Southeast Asia. And we're with React for now.

You can find me with that unsyllable handle on Twitter and GitHub.

Screenshot 2019 10 19 at 10 14 43 PM
Screenshot 2019 10 19 at 10 14 43 PM

The most content of my talk today comes from my experience in the past year writing docs for React Redux, which I've written a fair portion of the revamped docs for,

this then led to me working on Docusaurus as a maintainer. For people who've never tried Docusaurus before, it is a static site generator for documentations based on React.

So you can probably see that I have a lot of faith in docs, why? That's partially what I'd like to share with you today.

Since we're also talking about learning, let me give you a bit more context about where I am with respect to my own career.

I've recently passed my forth year as a full-time, front end developer. Although, I'm not one of those who are super talented, nor do I have a computer science degree. But perhaps that makes me a better person to talk about learning since I know exactly how I got better.

Year 1, playfully enjoying being a front end

In my first year, I enjoyed the job as if I'm playing Lego, assembling pages from PRDs, API documentations, and design spces, it was very playful and I had a lot of fun.

Year 2, "meeting my peers" and feeling everybody super good sia

I joined my current team in my second year, where nearly all my teammates had a computer science degree and are good to a level I was unable to evaluate, so it was like "meeting the peers of my major" but feeling slightly underqualified.

Year 3, building a lot of features

In my third year I got a bit lost in building features, a lot of features, but only features.

conference for inspirations

So hoping to get some inspirations from what other front end developers were doing in the world, I looked out for a conference to go. I ended up going to React Rally, it was very welcoming, and it's also where I picked up the project I speak of today. So I really hope I can pass on the spirit and be inspiring to someone in our audience as well.

Then in my fourth year, I spent a lot of time organizing a podium for my team where we talk about things we find intersting as a React developer. I myself gave a lot of talks there as well. I'd say that speaking and writing share a lot of things in common, I believe that a good talk is also a read, they both will boost your learning. For today we're gonna stick mainly to writing.

outline for today

  • learning from writing docs / 写文档学到什么
  • tackling the challenges / 技术写作的挑战
  • the value of docs contribution / 文档贡献的价值

For an outline, I'd like to first talk about what we can learn from writing the docs and why it is such a powerful tool for learning.

Then, I want to share with you the most critical challenges of writing documentations for myself. We'll talk about how we can integrate some practices we can do on a daily basis that will gear us towards writing better.

Finally I'll talk a little bit about the value of docs contributions, how they can be a unique chance to create great impact.

There are a lot of links in my slides and I will share the link to my slides in the end so you don't have to worry about missing stuff.

...rewind back to React Rally 2018

Let's go back to a day of React Rally 2018. It was my first conference trip. I was very shy and didn't speak to many people. The day after the conference, however, I found myself sitting in a table with a group of developers and speakers, having some casual conversation, where,

rewrite docs for redux
rewrite docs for redux

Mark, a maintainer of Redux, was also there, and at some point of time he mentioned that he was looking for people to rewrite docs for Redux and React Redux and asked if we were interested to help.

PNG image 7CC7CEF3C9BC 1
PNG image 7CC7CEF3C9BC 1

What will be your answer?

For those of us who may not be familiar with the React ecosystem, Redux is this really popular state management tool in the React community.

(The idea is it maintains all the data of your app in a big object, and you "reduce" the store states by dispatching actions, and you provide the "reducer" functions which specify how your store should update according to those actions.)

React Redux, then, is the connector to make your React app work with Redux.

  • am I senior enough? / 我够资历吗?
  • do I know much enough? / 我懂得够多吗?
  • writing is hard... / 写作很难……
  • I'm non-native speaker of English... / 用英文解释问题的能力

I was attempted, but I felt more uncertain about how much I could actually do.

Am I senior enough to write docs for such a popular project?

Do I know much enough about Redux or React Redux in order to write a complete set of docs?

And writing is haaaaaaard, plus I think words aren't really my thing, I hated to speak and write when I was a kid. I genuinely believe I am on the lower bound of born writing skills and so if it's something I figured out how to do, most people should be able to as well.

Not to mention that I'm a non-native speaker of English, so explaining complex ideas in English as a second language will take us more articulation.

If you have something that you debate over for like two weeks, suggestion for you: go for it. Can't know until you've tried. So after two weeks when I was back home, I reached out again.

PNG image BA053CBA2E96 1
PNG image BA053CBA2E96 1

And Mark, on the other hand, already had the project planned out in two GitHub issues for where he listed out the outline of the docs, the topics he wanted to cover, how to organize them, he also included a list of resources we can use as reference.

re-learning React Redux / 重新学习React Redux

  • ...and realizing that i don't really know Redux and React Redux
    意识到,我不怎么懂React Redux诶

So I did what you'd normally do studying for exams, and scared myself by realizing... I don't really know React Redux...

In case you're not familiar React Redux, let me show you first what kind of code you'll write with React Redux:

With a lot of details omitted, here's what your code will roughly look like. You create your store with Redux. It's supposed to contain all the data of your app, and you "provide" that store in your app root using a wrapper provided by React Redux.

import { Provider } from 'react-redux'
  <Provider store={store}>
    <App />

You can then write your components as if they already have the data that they need from the store. But they don't,

const Greetings = (props) => {
  const myName = props.myNameFromTheStore;
  return <div>
    <input onChange={props.changeName} />
    <h1>Hello, {myName}!</h1>

until you "connect" them to the store. There are two tongue twisting functions involved, one for you to get data from the store, the other for you to dispatch actions to the store, which is how you update the store,

import { connect } from 'react-redux';

// const Greetings = ...

const mapState = (state, ownProps) => ({ 
const mapDispatch = {
  changeName: (newName) => ({ type: 'change_name', newName }),
export default connect(mapState, mapDispatch)(Greetings);

You can probably see the APIs are very declarative. They do exactly what they say they do. So I've had no trouble writing this since day 1, when I copied the code from somebody else. And for two years I've never really bothered to care for what is really going on under the hood.

Now, it seems to me that this is a perfect example of me knowing the name of something without knowing it at all!

Anybody knows Richard Feynman? He's a physics professor, a Nobel laureate. He teaches physics in a very sensible way.

His lectures and talks were so great that people transcribed them and published as books. In one of those collections, Feynman mentioned that when he was a kid, his father had once told him about a kind of bird. He told him the name of the bird, in fact, he told him the names of the bird in multiple languages, and showed him that that is not the same as knowing what the bird is. In fact, you can know all the names of a bird in all the languages in this world without getting to understand anything about the bird at all!

Isn't this exactly the same as us knowing how to call a function without understanding the API at all?

This scares me, to be honest. Nowadays, our libraries and toolings are built towards better "developer experience", encapsulating all the heavy lifting inside the library so that we don't have to worry about them.

It's a good thing most of the times. We can happily build our features and go home early every day. But have you also noticed that we now can actually get away with doing our job quite alright 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? When we clock our miles implementing a lot of features, when is our chance to go in the other direction, to go deep into understanding our field?

Let's look at an example. For those of you who use React Redux, have you ever wondered, when will mapStateToProps functions run?

When do mapStateToProps functions run?

  • all mapStateToProps functions run whenever the store state changes
    每当store state变化的时候,所有的mapStateToProps都会跑的喔😯
  • this means that the performance of mapStateToProps matters

Did it ever occur to you that whenever our store state changes, each of the connected components will have to figure out whether the part of data it needs have updated or not. So all of them will run their own mapStateToProps functions.

Now, our pages may not contain just one, or two, connected components. Sometimes we have a lot of them. If all are calling their mapStateToProps functions, this means that our mapStateToProps functions better be fast.

We now tell you in the docs to try to make them as fast as possible, memoize them if needed, and NO ASYNCHRONOUS CALLS, plus they should return only the relevant data that its connected component cares about because it matters to whether the component will call their render or not.

Now, although performance issues may or may not be of our urgent concern, but will you agree that this is probably some under-the-hood we should at least understand, that there are intended ways how mapStateToProps functions should be written, but that is not something we can learn only by looking at that very declarative function call. If we're not careful, we can easily be that boy in Prof. Feynman's story, knowing only the name of the bird without understanding what the bird is at all.

PNG image 2B21D140AAFC 1
PNG image 2B21D140AAFC 1

As a college math major I've learned a lot of obscure facts that aren't really useful. This time, however, for a first time, I became the person in my team who understood why sometimes 120 item cards were calling their render functions whenever the user logs in, an action that is completely irrelevant.

That had a subtle impact in me. I became slightly more confident and much more interested in all the things about React Redux.

So... how does the learning actually happen?

Let's pause here a little bit. I wouldn't have done my talk right if I do not tell you how exactly the learning happens.

🤞 writing docs provides the ground for a thorough research
🤞 文档写作透彻了解这个领域的机会

First of all, writing docs provides a ground for a thorough research. If I am only to, say, figure out a specific problem I encounter the other day, chances are my learning would end at the point where the problem is resolved.

Maybe that is why a lot of times our "years of experience" matters, because we'd pick up those understanding little by little by running into and solving problems.

Now, since we're on a goal to write docs, this is the exact situation where we should go in full capacity to learn everything we can about the subject. For React Redux in particular, Mark has a repo containing a handful of good resources in the subject. I may have read one or two links out of it previously. But when I worked on its docs, I tried to read as many as I could. And if you've ever exhausted your reading in a subject matter, I think you know what I'm talking about.

☝️ "teaching" is the best way to learn
☝️ “教学”是最好的学习方法

Secondly, and here's our favorite physics professor again, Feynman has been advocating a method in learning called "the Feynman technique". Namely, you learn a subject by teaching it to a toddler, during which you find the gaps within your own understanding, and then you refine and simplify to gain better understanding.

Writing docs is like this process going over and over again until your docs are well-written.

✌️ people will review your work and provide more insights

Thirdly, if we are writing docs for a popular open source project, people will come and review our work. But not just normal users. In fact, domain experts, maintainers, or the people who created the library, they will review our work. Because they care about how the community uses and understands the library, they care about what we teach to new users, they care about what is being said on the official documentation.

But then, for us, someone who is learning the subject, isn't this the best mentoring we can possibly get?

So on the day my first piece of doc was merged, I thought,

... everybody should be doing this, right?

Everybody should be doing this, right? But, erm, no. Very few people are doing it.

At first I could not understand. I was like, people should be fighting for chances to work on docs. But, I was wrong. And over time, I kind of got an idea of why this isn't happening.

  • we didn't know that we are welcome to work on docs

First and foremost, I think a lot of us never thought we can work on docs but - today you know.

  • time and commitment for non-trivial docs contribution

Then here it comes the time and commitment issue. Trivial fixes like typos may not take a lot of time, but writing a complete set of docs requries a lot more commitment, collaboration with the maintainers, maybe multiple rounds of revisions on the draft.

  • writing is frustratingly hard

Then we all know that writing is frustratingly hard. Even Pulitzer winning authors will tell us it is hard. It is hard for everybody, and for us who don't write for a living it's a separate skill set that that a lot of us never chose to build.

  • understanding and explaining complex technical ideas

And I think the most critical challenges are centered around understanding and explaining complex technical subjects.

We're talking about writing docs for projects that we didn't write ourselves. We can't feel confident enough unless we gain some thorough understanding about the subject matter. A lot of times that comes brutally down to how well we understand the source code. That itself already being a hard bone to chew on, when it then comes to explaining it to another person, I always found myself powerless in words, regardless of whether I'm using my native language or not.


Understanding and explaining complex ideas 🧙🏻‍♀️🧙🏻‍♂️

So this brings us to the second part of my talk, where I invite you onboard to this major challenge for myself and share with you some thoughts along how I am tackling it.

It turns out that I think the understanding and the explaining are two sides of a same problem. 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'll get a refined understanding.

(no slides)

So after we've roughly wrapped up the few main sections in the newest set of React Redux, it was the end of last year, I decided that I wanted to build this skill set long term, maybe as a side project, or, to put it in another perspective,

are there systematic ways to gear us towards understanding and explaining things better?


maybe a personal one, I realize that since I speak very little, and write very little throughout my life, it doesn't make sense for me to be good at this. Therefore, are there things I can do on a regular basis that can systematically gear me towards understanding and explaining complex ideas better?

I think there are.

Let me ask you this: What do you do when you've either read an interesting technical article, or watched a good talk, or, found solutions to a problem you're tackling with, or have encountered an interesting library?


What do you do when you've:

  • read a good technical article / watched a good talk?
  • found solutions to the problem you're tackling with in a GitHub issue?
  • encountered an interesting library

💡 summarize the content in your own words, explain it to someone else 💁🏻‍♀️
💡 用自己的语言提炼总结,找个人给他讲一遍 💁🏻‍♂️

Try not to stop at bookmarking it, instead, summarize the content in a few words of your own, then share it with someone else.

For me what happens is, the first time I explain something, it nearly always goes worse than what I expected. Like, in my brain it was all planned out nicely with bullet points, one two three. But out of my mouth it all falls apart. It will only take you a few tries to realize what Feynman means by "find the gaps in your understanding", and then how "refining and simplifying the language" will feel phenomenally rewarding.

  • 🌟 1-to-1 sharing 🌟
    🌟 一对一分享 🌟

I think it works best if you have a coding partner who you can conduct 1-1 sharing with on a regular basis.

If you've never done it before, it may feel a bit strange. If you remember my recap for yesterday, that's not exactly how it goes for me but close. We normally won't have so many items to talk about, but they'll be more in-depth. Collectively our project crew knows very thoroughly what each other is doing and it's such a great chance for me to sharpen my understanding.

Once again highly recommended, please try it for a few times and feel its effectiveness yourself.

  • tweet your summary
  • (problems / GH issues) write a few lines of comments explaining the solution
  • open a "short notes" section in your blog

If you do not have a regular coding friend, then there are some similar activities you can do.

You can tweet it. But don't just retweet, put a few lines of summaries such that your followers can have a heads up of its key points.

If you're trying to solve a problem in your code, then just toss back the link, write a few lines of explanation such that the people who need to understand the situation can save some time.


one key is to fit this into your regular (daily) routine


One key is to make this a routine, make it "bite size" so it fits nicely into your regular if not daily routine.

The 1-1 works exactly because it's low profile, it's on small scales, it's not on record, you don't do a full preparation like a talk, instead you spend a few minutes to think through and maybe articulate your words before delivering it on the fly.

if you're doing the "short notes" or "todayilearned" section on your blog, make the layout makes sense for those smaller notes. Don't block yourself with longass blog posts that you won't finish in two weeks.

If you do this as a daily exercise, chances are you'll have clusters of those little notes and in two weeks you may have collected enough to make a bigger point.

💡💡 don't repeat what the code says, tell us about its intention

Here's the second thing I learned about explaining things.

What essentially we're doing is closing the gap between the languages that computers understand, which are often imperative, to the languages that another human being can understand. So don't repeat what the code says. Instead, be intuitive, tell us about its intention.

Have you ever seen some comments which, if you read the source code out loud, it's nearly the exact word-by-word match with the comments. They look like they're trying to explain things but they really aren't.

const factorial = n => {
  // create cache if there is none
  if (!factorial.cache) {
    factorial.cache = {}
  // if n is in cache then return it
  if (factorial.cache[n] !== undefined) {
    return factorial.cache[n]
  // if n is zero, set cache of n to 1
  // otherwise set it to n multiplied by the factorial of n - 1
  factorial.cache[n] = n === 0 ? 1 : n * factorial(n - 1)
  // always return from cached results
  return factorial.cache[n]

Don't do that.

Instead, be intuitive. Be like a guide.

const factorial = n => {
  // initialize cache
  if (!factorial.cache) {
    factorial.cache = {}
  // short circuit and return cached result it is already there
  if (factorial.cache[n] !== undefined) {
    return factorial.cache[n]
  // by definition, fac(n) = n * (n-1) * (n-2) * ... * 1
  // it is possible to recursively compute factorials with 
  // existing results by fac(n) = n * fac(n-1)
  // with initial case of 0 to return 1
  // the cache further reduces computations needed
  factorial.cache[n] = n === 0 ? 1 : n * factorial(n - 1)
  // cache[n] was just computed and we're guaranteed for a return
  return factorial.cache[n]

Let's now take another look at this memoized factorial function. Instead of repeating the code, tell us that we first need to initialize a cache, tell us that we can short circuit function return by taking computed values from the cache. Go a step further into explaining the motivations behind the code.

Then here again before going into the computational step, give us a recap of the definition so we know we can treat that as a given, tell us how the recursive step is based on the definition of the factorial. Provide an alternative explanation in your own words, basically,

remember that Professor Feynman said "toddler",

...tell us the "whys" of what it does and the "hows" of its complexities

and tell us the "whys" of what it does and "hows" of its complexities

what this part of the program does is...

how we do this is...

For example, you can start your comments like this, "what this part of the program does is...", or "how we do this is...",

  • what mapState does is...
  • what mapDispatch does is...
  • what connectAdvanced does is...
  • how the factory function pattern is used by React Redux is...
  • the case where you want to have customized performance optimization is when...

You can do this as you read the source code. For each part of the program, you can take some bullet points as you read the source code.

Before long, you'll have a bunch of notes like these. And they'll become some good starting points for docs.

💡💡💡 start writing docs with motivations too
💡💡💡 写文档的时候,也可以以动机来开头

The same drill applies to docs writing. Here's my magic line, "the goal of this piece of doc is to..."

  • the goal of this piece of doc is to... / 这部分文档的目标是……

When I start writing a doc, I always put this line on top. It's not permanent. Feel free to remove it later on. For me it serves two purposes. One, it gives me a lead in my thoughts. It's like a one-liner of what exactly I want to say with this piece of doc. And two, it gives me "conversation mode". Once I put down that line, I can start talking.

what about
English and writing?

And now it comes this classic problem, what about English and writing?

there are more people on the web who can fix your grammar issues than those who will make the non-trivial efforts to write the docs


For that, 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 make the non-trivial efforts to write the docs. So please don't let this stop you before even trying.

Plus, nobody speaks perfect English. I do not speak perfect English, I speak with like a funny accent I picked up from all over the places. But it's whether you can use your language skills to make the contributions that matters.

then, let's talk about a few tips...

Then, aside from the normal things you'd do to improve English, I can share with you a couple of things I repeatedly do as I work on docs that I found particularly useful for non-native speakers.

And I'll share with you a short list of resources in technical writing and English at the end of my talk.

  • use tools like thesaurus / 使用诸如同义词字典等工具
  • proof read our work / 语法审查

language tools such as thesaurus

Pick up a few language tools that are handy for you. Thesaurus, for example,

This is a cheating trick. Why it works is that it is harder to come up with words than to pick one from a list of words. Most dictionaries even allow us to do this recursively, and come with nice examples.

And don't feel fraud by doing this, this is something a lot of native speakers are doing that we aren't.

Then how do you get a feeling of which words are more suitable than others? For this you'll need to read more. But reading is easier than writing!!!

proof reading

proof read a few times each targeting a single type of errors


  • typos / 拼写
  • punctuations / 标点符号
  • subject-verb concord / 主谓一致
  • tenses / 时态
  • passive tense / 被动语态

Another thing I notice that we may overlook is proof reading.

I think most grammar issues can be resolved by proof reading. But we may not know how to properly proof read. What I do is I conduct multiple proof reads, each targeting a single type of errors. It's very objective, you can't get it wrong.


how are we doing now?

  • explain things to others
  • routinely practice this, 1-1 sharing, "today I learned" short notes
  • be intuitive, don't repeat the code
  • start with motivations i.e., "...the goal is to..."
  • start trying in English, find tools that work for you
  • proof read your work

We've talked about a lot of stuff, let's take a look back. We started at how we want to explain things to others better, then we talked about some killer drills we can do on a daily basis, we agreed to be intuitive and talk about motivations, we talked a little bit about English, and we'll remember to proof read.

How are we doing now? Feeling eager to try a few of those?

a few months later...

PNG image D9117B12CDE8 1
PNG image D9117B12CDE8 1

A few months later it was mid year this year, Mark was looking for an FAQ entry to be added to the Redux doc, what do we do this time?

Turned out, it was one of those moments that "clicked". Since the topic was already discussed everywhere, the opinions were more or less objective, all I needed to do was to make sure I understand everything, and put them into an entry that fits the context of an official documentation. I had a eureka moment when I created that PR, and I really hope that you will join me in a near future. case you need a bit more motivations

But just in case you need a bit more motivations right...

📚 is it redundant?
📚 网上已经有那么多教程和博文了,再写文档算是重复工作吗?

You may wonder, if something is already talked about in multiple places, it may seem redundant to say that again in the official docs. But chances are, if something is said multiple times elsewhere, it may exactly because it is both important and not addressed in the official docs.

🥇 docs are a unique golden place for information about the library
🥇 文档占据我们理解框架过程中独一无二的黄金位置

Official docs has this unique place that it will likely be visited prior to other resources, and whats more important is that people will treat it as more sound than others.

If the answer users are looking for can be found in the official docs, they don't need to look elsewhere - it saves their time. It will in turn save more time because the posts won't need to be written if it's already said in the official docs.

And that's one fewer confusion by the community, that's collectively better understanding and that's very powerful.

(So if you have the chance to work on those entries, to organize those issues into the official docs, do it. Thanks to your effort those hot topics are now in the official docs. Next time your colleague ask you again those questions, you can just toss them the link and say that "it's in the official docs :]")

👩🏻‍💻 can it benefit your work
👨🏻‍💻 这能和日常工作结合起来吗?

If you can find some tasks from your work that are related with the project write docs for, or vice versa, your work tasks use something that is looking for docs contributions, I strongly urge you to do it because it benefits many parties.

  • you learn directly from maintainers

You contribute to the OS project on docs. You'll be directly speaking to its maintainers,

  • your tasks gain access to "official" support

this means if you have questions as you work on your actual work task, you have close access to official help.

  • maintainers care about your use cases

Then, it should not surprise you that the maintainers care about your use cases,

  • be an early adopter of experimental APIs

especially if they're developing new APIs and are looking for early adopters. Be that early adopter. Your feedback may be adopted and that makes you not a follower but a creator of the future.

  • you can become the domain expert in your team

And all in all it benefits you the most 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 time you spend in the company.

Next time when someone look for docs contributors, will this be you?

Next time, when someone look for docs contributors, will this be you?

Before we end this journey, let me point you to a few resources if you pick up some docs writing in the future.

a list of well maintained docs

To prepare for this talk I have created a repo for a list of projects of well maintained docs that I've personally learned a lot from. So it's a personal list for now. But I hope if anybody knows more, feel free to PR to add to this list.

a short list of English / writing resources

I have a very short list of resources I find interesting in English and writing, you can read my personal remarks on my slides (which I'll share the link to you in the next slide).

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 a very fast and lightweight read as well, good to get you started I think.

On Writing Well is a more classy book on writing in general. Slightly opinionated and very amusing to read.

Good Prose is a personal favorite. It's written by a Pulitzer Prize winner together with his editor. It's not as relevant to our industry as the first two but it's very beautifully written, very insightful. Recommended for those who want to go deeper into writing.

Then finally Elements of Style is a classic guide to writing style. It has been my middle school, high school, then college writing class must reads.