5 Lessons Learned Contributing to an Ethereum Open Source Project - Austin Akers

uh hello everyone my name is austin akers i'm a software engineer at software engineer 2 at microsoft and i also do open source contributions to the metamask documentation and also the metamask extension so with that being stated uh throughout my two and a half years almost three years just being an open source contributor to uh the metamask documentation and extension um i have five lessons i've learned contributing to an ethereum open source project so i had like 20 but for the sake of time i didn't want to bore y'all and i wanted to narrow down to five so let's jump into this so as a quick overview uh we'll then start i'll then talk about the whole background like how did i get started contributing right and then from there uh i'll then talk about like essentially what i've learned along the way contributing again to the uh extension and also the documentation and last but not least uh if we have time i'd love to have a quick q a if that's possible i don't know if i'm able to but if so let me do a quick q a not q a uh don't be shy uh ask ask away okay so that being stated let's get started so how it began now this all began uh back in 2019. i went to a a conference called truffle con anyone ever heard of that no anyone heard of like the truffle suite right anything like that so yes so if you're not familiar with truffle suite they build out tooling to help improve blockchain software uh smart contract deploying and everything like that so i went to this conference and uh you know with a couple friends one of them over here and uh we just as i said we're sitting down at a table and a random developer a developer actually turns out she was from metamask and she approached and she asked hey if there's one thing you can improve uh with metamask what would it be and for me i was sitting down i was like uh i don't know and then my friend shouted out the documentation and i told myself oh yeah the documentation and so uh and i said and i actually then after that i took a step back and i said hey you know instead of me asking you all what you should improve why don't i try doing it myself so that same day i actually went ahead uh created a repository uh forked the metamask documentation and did an entire redesign so a lot of the stuff which y'all see today is uh yeah due to that and about at the you know about a couple months of working on that i went ahead and sent the team a documentation prototype and that was around november of 2019 and then about february of 2020 as when they deployed it so uh yeah so that's kind of what happened and then from there it's just only been me contributing more so with that being stated here are five lessons i've learned contributing to the metamask extension and also the metamask documentation the first one being treating documentation like the other 50 of your product i think far often tonight even as engineers in general we actually put documentation as secondary and actually it should be just as important if not more important than the product that you work on and the reason why is because documentation in general is a gateway to the product so and it's actually very important too because a lot of individuals especially as we start building out things in the web3 space right we're wanting to onboard users and in order to do that you have to have frictionless documentation because again if someone who's not too familiar about the blockchain space the first thing they're going to go to is let's say metamask.io and then going to the getting started guide because they won't know how to get started so that's your gateway and that's the other 50 a lot of people tend to not take it a true consideration um and with that being stated right as you're building it out like the you know like your other 50 making sure you define a structure i think as engineers what we end up doing is that we ended up doing a knowledge dump and we expect people to just oh yeah just yeah i just dumped all this here you can go and look at it so you have to actually be able to have a defined structure with whatever your uh you know with your documentation and the same thing as you would with an uh an application right it's not all over the place you have a defined structure how things work being able to replicate that as well within the documentation is just as important and last but not least uh within this is making sure it's a continuous process you aren't just you know putting this information out here you have to continuously audit what you're doing the same way as an engineer when we're going back refactoring code you have to act the same exact way with your documentation saying asking yourself hey like okay this is pretty interesting but let me go and go back audit this and find different ways to go about improving this which brings me to my next lesson um you know within auditing right this is cool we've defined a structure we've audited our documentation well over the past six to eight months i've actually started reading a lot more about how to build out well-defined documentation right and uh i actually figured out that there are about roughly four themes in documentation right so four different distinct themes within documentation uh initially when i started building this out i thought it was just two things first thing being documentation just consists of tutorials and just reference material and that's about it but turns out it's a lot more than that and after reading so much about how to improve right wanting to make the experience a lot more frictionless for individuals wanting to enter the space i had to take a step back and ask myself what exactly is documentation and um after reading again a lot of books articles uh ironically there's actually four distinct themes and those four distinct things start off with again tutorials guides so how to do something right um explanations and also last but not least reference materials so being able to reference back uh having individuals be able to have an ability to reference back and these four distinct themes is what makes documentation very successful right um and really lowers the barrier for individuals to be able to enter into whatever you're building out like working on your tool or building building out and building on top of your tools so um yeah as i said exactly that and you know going into lesson three uh you know after defining these four distinct things right you've now broken into your documentation and in fact if you want to know about better documentation look at uh vue.js phenomenal documentation uh pie charts pie torch um i think what flask as well too angular react they all have phenomenal documentation but you've now broken the sound you've defined a structure you've now figured out there are four different themes the next bit is writing with empathy now a lot of us here who are pioneer a lot of people who are pioneering in the space have a lot of knowledge and with that being stated being able to take that knowledge that you've acquired while building out let's say a blockchain building out protocols um you need to make sure you can take that and uh use that and actually approach writing things whether it be from the code that you write to the documentation that you write and you have to figure out how to close that knowledge gap right and also with that right while you're closing that knowledge gap uh not assuming because not everyone here is a senior engineer not everyone here is a mid-level engineer better yet not everyone really in general is familiar with just web3 in general so being able to not only close that knowledge yet but while doing so not assuming that that individual is just automatically going to read what you've just written and expect uh and expect and you expect them to know it so you should be able to write effective anything effective code that's easy for not only just a senior engineer right but also a junior engineer too right and last but not least um you know yeah you're writing with empathy but how do you sort of receive feedback you have to do user research the same way with as i said building out of the extension how did metamask get better how did any sort of application that you all build out get better it all happened it all goes upon the whole idea of doing user research which brings me to lesson four uh discovering feedback sources now uh contributing to uh yeah just contributing just in general right uh to the doc to the metamask docs and and the extension as well uh i've had to figure out there are three distinct ways for me to be able to receive feedback to help improve the overall well-being of just the ecosystem in general right because that's something that is referenced a lot so the first one being which i learned really interestingly enough being a contributor is reviewing github issues and that sounds really straightforward but you'd be very surprised a lot of the projects out here a lot of people just don't actually sit down and try to review a lot of issues um and to be quite frank with you um it's really is really interesting next up is reviewing pr's so you have reviewing github issues right where you're taking a look someone's saying hey oh my this transaction's not working the way or send transactions not working the way i actually thought well then reviewing pull request actually approaches it in a completely different manner where people put in saying hey you know what i think it can be improved this way so understanding the community and also understanding and knowing that the community themselves are saying hey you know what i think it could be better explained or better yet it can work even better this way here's why so reviewing pull request is just as essential if not more essential as well to reviewing the issues and sure we have these two things but let's be honest here not everyone here like how many of you have a github by show hands not everyone but a lot of people that's awesome right uh yeah it turns out as i said again you have to have different means of being able to interact and communicate with the community so so being able to talk directly with the community right so that means again a lot of people have discord channels um telegram groups and just being able to figure out those ways to again lower the barrier to entry for you to be able to receive feedback from your users because not every meta mask user not every honestly user of your product is going to be an engineer it's not going to have um you know sorry it's not yeah not everybody not only are they just not an engineer they also just don't have a github so having those means of being able to receive those other means of community feedback uh and that actually is proven to be very interesting and also comes with again talking to people directly in person so and last but not least uh well i'll look at this right here so we've looked at reviewing github issues reviewing pull requests and talking directly to community it sort of creates this feedback loop where you do something you then measure it and how do you measure that right you measure it by looking at the amount of issues about that one specific thing that's problematic uh reviewing pull requests and then after that you're analyzing and saying hey what exactly is the community actually saying and really trying to better understand that uh and then last but not least do you correct it well sorry another thing you correct it like hands down if the community is saying hey something's wrong here or hey i'm not really understanding how this works and they're giving you a lot of feedback doing what you can to do to actually correct uh like specifically what's you know what's uh sort of like what's fuzzy for them right or what's exactly uh like what's not necessarily working right or something broken so um and then just repeat it and it's a continuous process and lesson five which i think is the most important part especially being in this space being okay with saying i don't know but yet so when i first started working on the uh on the uh documentation to be honest with you i mean i thought i knew a lot about ethereum i honestly thought i did but after actively working on the actual documentation i learned a substantial amount from uh everything from how ethereum dot request works to the innards of how you know as i said just innards of even just you know how uh metamask or the extension or even works directly like with smart contracts right so being able to understand that but being okay with saying i don't know yet and that's very important especially in this space because again in comparison to a lot of other spaces out here like i mean what this is still relatively new so um the first thing you have to ask yourself when approaching any sort of situation and anything that you're wanting to contribute to is like why does it work this way and how exactly does it work and i did exactly that after working on the uh documentation i started contributing more to the extension right and uh in fact uh fun fact i actually ended up figuring out ways uh because i didn't i had no idea and if you ever has anyone ever looked at the metamask extension uh github like the codebase it's vast and it's actually sometimes very intimidating and what i ended up doing was uh trying to find one bit of relevant code digging into the code base and finding one bit of relevant code that little bit of knowledge but establishing that foundation and then building out from there and i did exactly that in fact i wanted to know how transactions work right the whole idea of sending transactions worked and i saw an issue and this issue said hey you know uh there's an issue filed like hiding links to ether scan like when no black explorer is like specified for a custom network so long story short uh hiding the ether scan link like whenever you have that oh uh confirm transaction or just hiding that if it's a custom uh if it's a custom network right because then you end up having like some network and it's linking to like the ether scan link in reality it's yeah yeah it's a set of it's not uh not a part ether scan so what i ended up doing was digging that little bit of relevant code and it ended up bringing me to the etherscan library and ironically instead of putting that pull request and fixing it there from that knowledge that i built upon right actually uh cloning or forking the etherscan link library and actually making that uh making that fix there and so with that being stated not only are you digging into that bit a bit of relevant code don't be afraid to even as an engineer venturing into the dependency tree i think uh far often to not what we end up doing is we ended up saying oh it doesn't work let me just go and file an issue like no take a step back like find out okay what actually is the dependency uh like what dependencies actually what's being used here let me go ahead and fork that let me go and take a look and actually dive into that and i feel as though that's not only important for the security of the uh code base that we built but also just understanding and broadening your knowledge of how the innards of the libraries that we use day to day actually work so but overall though um like how do i feel about like contributing to the uh extension contributing to the documentation especially the documentation i think it's great i love it is it tiring i'm not gonna lie to you it is i work full time at microsoft and then in the evenings i hop on and uh you know outside of spending amazing time with my lovely wife uh being able to hop on and uh try to you know figure out ways to better improve and facilitate uh means to be able to you know lower that um lower like that that friction that gap between individuals getting into web3 wanting to actually make a meaningful contribution it's tiring yes do i lose motivation i mean if you're writing more than 40 hours a week of code i mean let's be honest here you sometimes lose motivation and uh but you know am i constantly learning in this space yes not only do i have to be if i'm wanting to one if i'm wanting to write effective documentation for all of you but i'm also just learning constantly learning for myself and but is it rewarding and i put this in all caps because yes um hands down i think the best part about being an open source contributor being able to work on relevant products that you all consume is that at the end of the day being able to put a smile being able to help that individual build their very first like creating a simple simple decentralized application in my opinion it makes me happy make essentially making you happy i know it's like really simple but like i genuinely enjoy it um so it is rewarding in the sense of being able to see the smile on people's faces and being able to make effective contributions to the ethereum community but also bonus lesson definitely work on a project you're like passionate about so again i've been really passionate about metamask and i had no idea initially a way to contribute and the documentation was phenomenal to be able to start from but again work on something you're passionate about and that right there also makes a huge difference so with that being stated uh if you all like like this talk follow me on twitter i'm tweetmonster999 okay uh follow me on github b-boy acres yes i'm a breakdancer as well hence the b-boy and uh also last but not least connect with me on linkedin if you want to set up a call if you want to figure out ways to honestly contribute to the metamask documentation to the extension or anything like that i'd love to sit down and talk with you so again um my name is austin i hope you all enjoyed this talk and i again uh thank you so much and i enjoy being a part of this community i hope you all have a wonderful day