Beyond DX; Building World Class Developer Documentation for Web3 - Owanate Amachree

Transcript

so I'll be [Applause] calling wet to come and give her next talk please a round of applause for her I know I I crucified that name really really really a a hello everyone okay so I'll be talking with um I know there are some people here who have contributed to if you have contributed to document ation can you please signify before okay um how many developers here have built like documentation from scratch like gbook nice nice nice okay so there are

some challenges with web three documentation and as we all know um for an industry that is still quite in this n stage there's a lot of work we need to do in terms of content so yesterday I was speaking with I was speaking with somebody um here a developer was complaining about a chains documentation and um it to that how it was very difficult for them to get started and um do basically um have their first hello world right on the Chain so I'll be speaking with you um on how to build world class documentation for web 3 most of this um um stuff I'll be talking about has already been

implemented on root talk documentation so while I'm speak speaking you can just cross check with some of the stuff I've said and also cross check the root stock documentation and you'll be able to put uh one of one plus one together so this talk is for dog specialist so if you have worked on documentation before if you are a technical writer who contributes to documentation every time and um also if you're an information architect right you like architect the structure from the developer Journey how they will get started on a chain or how they will get started on on a particular topic on documentation this topic is very interesting and um please pay attention so I'm I'm a senior technical

writer at roock labs and um recently I was I led a project to rebuild the root stock documentation from scratch so when I mean from scratch from the very scratch we were using the JQ we moved to Gatsby and we then moved to Doros so there was a lot of learning process involved in that and like to walk you through the steps we went through to achieve that [Music] so so we'll be we'll be we'll be looking at how to understand the developer audience right how is it possible how do you understand who the which developer

is building on your chain and how do you like properly idate um or research and know what their journey and what their steps are before they before they do their first hello world on maybe polygon or on ICP or whatever so documentation is a Cornerstone for developer experience so it's not there's no doubt some of us how many of us refer to documentation whenever we listen or whenever we hear about any particular technology what's your first point of call documentation so it's a very key part of developer experience and with po documentation um trust me you do not know how many um how many how many developers or how many users are leing or have disinterested in

your technology so these are something that startups and companies in web3 need to pay closer attention to um and this talk documentation also helps developers understand and what use your technology and it also plays a a great role in driving the developer adoption and success on the chain okay so what are the unique challenges with web three dogs so it requires um adaptability right it needs you to understand the developer so is it an

ethereum developer is it a beginner to root smart contract is that a is that a um a beginner to maybe they need to learn about a certain technology before they get started so what are their Journeys basically and some some of the challenges includes SP information architecture so when you go to documentation certain documentation it's not really clear um um because the the architecture is not drawn is not designed for a specific user Journey it's not really clear on how you can start so it's a lot of scattered information sometimes the search does not even work and also we need to provide U one of the challenging is provide providing clear and concise accessible information so these are some

of the challenges with web three dogs at the moment Web Two documentation most cases does not suffer this right um like I said web 3 is still in this nent stage so what do you need to do um most of the in most cases startups begin with the call contributors or the call developers starting the documentation so like we all know developers that's not their call function so if you're developer if the developer of that chain is the one that sets up the documentation they're not going to pay attention to user res sech they're not going to pay attention to who the ideal user for the chain or for that um particular protocol who the ideal user is so it's difficult to like um design the architecture to suit each

particular user so for example for ethereum for root stock and for some of other blockchains we always know that there is a node operator we always know that there is a developer who is going to integrate your sdks who is going to deploy your chain right and we know that some protocols also have their own applications that means your documentation has has to cater to these different audiences it needs to C to the developer it needs to get to the no operator it needs to get to the honary and general user for that product so these are three users that I've highlighted and how do you structure the documentation so that if a developer is coming to um the polygon documentation they know how to get started from a development background and if they beginners if they are intermediate if

they um experts what is the ideal Journey for for those persons so know your user right understand what they what platform do they use do they use mobile do they use web um who are these developers are they web three developers are they Bitcoin developers are they ethereum developers looking to put to another chain so um what are their pain points what are they looking for are they looking to conduct their first hello world what are the tools they will need right um and how do we structure the documentation so that any person coming that is new to your chain knows that they have to start with hard Hearts they have to start with um um me right so what are their Journeys these are basically and what are they expecting

what do they want to do from the beginning create um an account or log into to your developer portal or whatever and build or start writing and then deploy and then blah blah blah do stuff on your chain so know your users it's very critical to know your users and um we'll be talking about information architecture so in some cases developers don't need need this information but it will be good if you have previously um if you have previously built a developer portal before and you want to like re re reimagine your documentation and then for technical writers who are playing on the top of documentation every day

please um based on what I'm going to be sharing I'm sharing with you now look at your documentation conduct proper research to know who your users who the users of your protocol are that way it's going to um you are going to effectively architect the journey based on the different users for your protocol so it's not it does not apply to all cases it's specific to your chain and you need to do that research to be able to onboard developers faster so most of the uh friction comes from onboarding stage and most of the time they interact with documentation or they go to Google or they go to stock overflow so what is the ideal Journey for the developer and how do they land on your docks and what action do they take to achieve a particular goal on your documentation so um user research consider mental models

so what are the familiar terms that developers know right you can't be talking about smart contracts and you are on the documentation it is referred to another another stuff right you we remember how um during when most times people explain blockchain using web true databases sometimes we they also explain blockchain using chains right a chains chains upon chains connecting connected together so that's a mental model we know how chains look like and we can relate that to what um blockchain we also know how the web two database works right but Web Two database has some blah blah blah security issues any developer can conduct do an SQL query and change the information meanwhile it's not the same thing with the blockchain so those

kind of mental models um what's the difference in web two and the difference in web 3 helps you to properly explain um to a user so mental models are important mental models mean I'm familiar with this term so use that same term in your documentation so that you don't um confuse confuse your audience so information have to do um architecture has to do with the user the content that they interacting with and in what context are they interacting with that content so for beginners for intermediate or for um experts so that's it for information architecture I'm going to show you um how to what this is a a a in the beginning phase this is a simple

information AR Ure all right here um you can observe that there are three there are three um like three buckets of information so we have the concept bucket of course anybody coming to a chain needs to understand what the chain does and the stack right the tools the stack and all that the foundation of the chain now you need to explain that in the concept bucket or whatever you T to name it but make it name give it a name that people are familiar with so that developers or whoever is using that documentation can easily um understand what and get into that particular bucket now node operators if you want to start up a node as a developer um depends on the Chain some chains have node specific

for node miners so if you have node miners using your chain that means this bucket needs to be different from the developer bucket because developers are going to interact with your chain using the RC so it's not really that um efficient if you tell them how to start a node but if you have um if that's the way you start your um a node on your chain please go ahead and put that information in that bucket so three I've done three buckets here I I purposely took out the developer bucket because it's not really peculiar not um Sometimes some chains have your developers need to set up a node before they do something in some cases you have the RC to interact with you okay so now I've broken this down um in this step I've added the

developer bucket now why did I add the developer bucket the developer bucket that means we have Concepts and concept can talk about what is ethereum what is RO stock what is M mining or what is um what is what are smart contracts on root stock or how smart contracts function on root stock and then we have the developer bucket this can include set up instructions so if you a developer coming to a documentation that has this four um this four bucket of information where are you going to visit first the developer bucket right you go to the developer bucket and you go to the set up and start from there on you see the hardware requirements and and how to set up your your um system your environment to start um deploying or

writing smart contract and then you have quick starts which can be U quick starts maybe sdks hard Hearts um VM and all that quick start and then we have the node operators you can teach if your chain uses um um has a separate um um environment or a separate architecture for not operators where not operators can benefit from Mining and all that it's necessary for you to separate that bucket and then you have um how the node operators can set up on your chain how they can understand basic um information about the node and all that and then we have the user so if your chain house products that they they run on their own that means you need user documentation for the general user who wants to maybe um Bridge from a chain to another chain

that bucket has to teach them how to do that so this is a um this is a at a very basic level this is what anation architecture should look like so what are the key take takeaways from this talk right I'm trying to hurry up use familiar Concepts in some cases you see developers write um they create end points that are not even the end point is not even does not concern the particular um uh page or whatever is being developed so that is one use case um use familiar concept that people are already familiar with it's not a it's not a joke right it's something that is also dependent on SEO so so if you have um if you're writing a page on how to

write smart contracts don't write don't do write SC as the page title put the proper URL which is right smart contract that way it's helpful for and when somebody is looking for um sear on Google how write smart contracts your chain um um guide can come up in in searches maintain consistency be consistent this is your technical writers and do contributors read the style guide always read the sty guide be consistent and maintain context um try as much as possible to minimize the cognitive load people are coming to the documentation to do particular stuff or to achieve a particular goal so please try to minimize the um the cognitive load and see how you can be as fast as

possible with your explanations and let them get to hello world if possible in 5 minutes if possible in 2 minutes depending on your setup and your chain so break down the two levels of expertise so if it's a beginner break down the tutorials and the guid into beginner expert and inmediate it's easier for um whoever is picking up that information to properly um get through so make the content goal oriented and actionable so what are the tools that you can use for now you can use miror uh miror is um very good for information architecture so it helps you to properly visualize the users and what content needs to go into different um buckets so we have Excel where you can do your

content event if you are a startup that already has documentation and you want to rethink your documentation use you can use Excel to like properly categorize the content again and do migration and all that kind of um stuff so figma for designers definitely this throughout this process the you the documentation manager or the technical writer whoever is in charge of this project needs to work with a designer like I said um in this beginning of the startup phase most times we don't do that right so um those are this are this is really what I want to talk and of what I've said here can you can see that it has been implemented in documentation you can see the call to actions which is quick start and explore the dog so beginner to web3 um deploy smart

contract become a node Miner apply for a grant those are different user Journeys and depending on the your your journey you can feel free to um check out any of those links so that is an example all these things have this is an example implementation and please if you have questions um kindly go ahead and ask me any questions I have one though yes please how much um if I if I want to join come into this line of um technical writing technical writing what is the entry level what is the because money can be a very good um motivation you know and most people are just looking like they are here for the

passion no yeah so what what are we looking at when it comes to to that okay okay when I started I started with open source contribution gitcoin I started contributing through gitcoin I was not a developer but what I was doing was user research for the teams I was on I I was in charge of preparing their slide deck and like um writing about the um the project they working on so I started from open source contribution so you must not be a developer um to contribute to open source so like I said um a lot of protocols have their um style guide they have a way to get started with contribution they have their contribution guidelines so open source is a great way to build that portfolio so the more um CH you interact with the more um your your PR get Meed the more

experience you can gner this is not to be replaced with actual work experience right freelance work is different from actual work experience but open source writing um you can go ahead and share knowledge whatever on medium depth or two not that's also a great for you to start building your portfolio once you have your portfolio together you can start applying for actual jobs because jobs wants to see your portfolio and there's no way you can get a portfolio if you don't start writing so that's the like so so so you don't want to give us an amount like like 5K 10K if if you get for beginner it depends on the open source it depends on what you are contributing about if it's an article it depends it depends on the Chain it depends on what they are giving out it

can go as as high as $500 can go as high as 1K on if it's open source and some of the contest so we have writing contest on Ro on hakon so if you go to Google search hakon um writing contest you see root and you can also write about root and you'll be also if you are eligible you will win the prizes so that's those are the ways you can get started please a round of applause for w for this amazing session