# Beyond DX: Building World-Class Developer Documentation for Web3

- Speakers: [Owanate Amachree](https://streameth.org/speakers/owanate-amachree)
- Channel: [Web3Bridge](https://streameth.org/web3bridge)
- Date: 2024-09-07
- Watch: https://streameth.org/watch/66d916d94f2179fbae7c660d

## Transcript

So I'll be calling Owanate to come and give her next talk. Please, a round of applause for her. I know I crucified her name. Really, really, really. Owanate. Owanate. Hello, everyone. Okay, so I'll be talking with... I know there are some people here who have contributed to if you have contributed to documentation, can you please signify before? Okay. How many developers here have built documentation from scratch? Like Gitbook? Nice, nice, nice. Okay. So there are some challenges with web3 documentation. And as we all know, for an industry that is still quite in its nascent stage, there's a lot of work we need to do in terms of content. So yesterday I was speaking with somebody here. A developer was complaining about a chain's documentation and how it's very difficult for them to get started and basically have their first hello world on the chain. So I'll be speaking with you on how to build world-class documentation for Web3. Most of this stuff I'll be talking about has already been implemented on rootstock documentation. So while I'm speaking you can just cross-check with some of the stuff I've said and also cross-check the rootstock documentation and you'll be able to put one plus one together. So this talk is for docs especially. So if you have worked on documentation before, if you are a technical writer who contributes to documentation every time and also if you are an information architect right you like architect the structure from the developer journey how they will get started on a chain or how they'll get started on a particular topic on documentation. This topic is very interesting and please pay attention. So I'm Awanate. I'm a senior technical writer at RooStock Labs and recently I led a project to rebuild the RooStock 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 DocuSource. So there was a lot of learning process involved with that, and I would like to walk you through the steps we went through to achieve that. So... So we'll be looking at how to understand the developer audience, right? How is it possible? How do you understand which developer is building on your chain? And how do you, like, properly update or research and know what their journey and what their steps are before they do their first hello world on maybe Polygon or on ICP or whatever. So documentation is a cornerstone for developer experience. So there's no doubt. 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 poor documentation, trust me, you do not know how many developers or how many users are living or are disinterested in your technology. So these are something that startups and companies in Web3 need to pay closer attention to. And this documentation also helps developers understand and watch use your technology and it also plays a great role in driving the developer adoption and success on the chain. Okay, so what are the unique challenges with Web3 docs? So it requires adaptability, right? It needs you to understand the developer. So is it an Ethereum developer? Is it a beginner to root smart contracts? Is that a beginner to maybe they need to learn about a certain technology before they get started? So what are their journeys, basically? And some of the challenges include poor information architecture. So when you go to documentation, certain documentation is not really clear because 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, one of the challenges is providing clear and concise accessible information. So these are some of the challenges with Web3 docs at the moment. Web2 documentation, most cases, does not suffer this, right? Like I said, Web 3 is still in its nascent stage. So what do you need to do? In most cases, startups begin with the core contributors or the core developers starting the documentation. So like we all know, developers, that's not their core function. So if you're a developer, if the developer of that chain is the one that sets up the documentation, they're not going to pay attention to user research. They're not going to pay attention to who the ideal user for the chain or for that particular protocol, who the ideal user is. So it's difficult to design the architecture to suit each particular user. So for example, for Ethereum, for Rootstockalk and for some 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 to cater to these different audiences. It needs to get out to the developer. It needs to get out to the developer. It needs to get out to the node operator. It needs to get out to the owner 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 the Polygon documentation, they know how to get started from a development background? And if they're beginners, if they're intermediate, if they're experts, what is the ideal journey for those persons? So know your users. Understand what platform do they use. Do they use mobile? Do they use web? Who are these developers? Are they Web3 developers? Are they Bitcoin developers? Are they Ethereum developers looking to port to another chain? What are their pain points? What are they looking for? Are they looking to port to another chain? So 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? And how do we structure the documentation so that if any person that is new to your chain knows that they have to start with hard hats, they have to start with Wagme, right? So what are their journeys? These are basically... And what are they expecting? What do they want to do from the beginning create an account or log into 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 we'll be talking about information architecture. So in some cases, developers don't need this information. But it should be good if you have previously built a developer portal before and you want to reimagine your documentation. And then for technical writers who are playing on the top of documentation every day, please, 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, 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 friction comes from onboarding stage, and most of the time they interact with documentation, or they go to Google, or they go to Stack Overflow. So what is the ideal journey for the developer, and how do they land on your docs, and what action do they take to achieve a particular goal on your documentation? So user research, consider mental models. So what are the familiar terms that developers know, right? You can be talking about smart contracts and you are on the documentation, it is referred to another stuff, right? We remember how during, most times people explain blockchain using web2 databases sometimes well they also explain blockchain using chains right a change change upon change connected 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 Web2 database works, right? But Web2 database has some blah, blah, blah security issues. Any developer can do an SQL query and change the information. Meanwhile, it's not the same thing with the blockchain. So those kind of mental models, what's the difference in Web2 and the difference in Web3 helps you to properly explain 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 confuse your audience. So information architecture has to do with the user, the content that they are interacting with, and in what context are they interacting with that content. So for beginners, for intermediate, or for experts. So that's it for information architecture. I'm going to show you how to, what, this is a, in the beginning phase, this is a simple information architecture, right? Here, you can observe that there are three, there are three, 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, 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 tend to name it, but give it a name that people are familiar with so that developers or whoever is using that documentation can easily understand what gets into that particular bucket. Now, node operators. If you want to start up a node as a developer, it depends on the chain. So chains have nodes 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 RUPC. So it's not really that efficient if you tell them how to start a node. But if that's the way you start a node on your chain, please go ahead and put that information in that bucket. So 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 the developers need to set up a node before they do something in some cases you have the rupc to interact with you okay so now i've broken this down 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. Our concepts can talk about what is Ethereum, what is Rootstock, what is Merge Mining, or what are smart contracts on Rootstock, or how smart contracts function on Rootstock. And then we have the developer bucket. This can include setup instructions. So if you are a developer coming to a documentation that has these four buckets of information, where are you going to visit first? The developer bucket, right? You go to the developer bucket, and you go to the setup, and start from there. You see the hardware requirements and how to set up your system, your environment to start deploying or writing smart contracts. And then you have quick starts, which can be quick starts maybe SDKs, hard hats, VM and all that quick start. And then we have the node operators. You can teach if your chain uses, has a separate environment or a separate architecture for node operators where node operators can benefit from mining and all that. It's necessary for you to separate that bucket. And then you add how the node operators can set up on your chain, how they can understand basic information about the node and all that. And then we have the user. So if your chain has products that they run on their own, that means you need user documentation for the general user who wants to maybe bridge from a chain to another chain. That bucket has to teach them how to do that. So this is at a very basic level, this is what an information architecture should look like. So what are the key takeaways from this talk? I'm trying to hurry up. Use familiar concepts. In some cases, you see developers create endpoints that are not even... The endpoint does not concern the particular page or whatever is being developed. So that is one use case. Use familiar concepts that people are already familiar with. It's not a joke, right? It's something that is also dependent on SEO. So if you have, if you're writing a page on how to write smart contracts, don't write, don't do write SC as the post title. Put the proper URL which is write smart contract. That way it's helpful for SEO. And when somebody is looking for searching on Google, write smart contracts. Your change guide can come up in searches. Maintain consistency. Be consistent. This is for technical writers and doc contributors. Read the style guide. Always read the style guide. Be consistent. And maintain context. 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 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 five minutes. If possible, in two minutes. Depending on your setup and your chain. So break down into levels of expertise so if it's a beginner break down the tutorials and the guides into beginner expert and intermediate it's easier for whoever is picking up that information to properly get through so make the content goal-oriented and actionable so what are the tools that you can use for now you can use Miro, Miro is very good for information architecture. So it helps you to properly visualize the users and what content needs to go into different buckets. So we have Excel where you can do your content inventory. If you are a startup that already has documentation and you want to rethink your documentation, you can use Excel to like properly categorize the content again and do migration and all that kind of stuff. So Figma for designers, definitely throughout this process, the documentation manager or the technical writer, whoever is in charge of this project needs to work with a designer. Like I said, in the beginning of the startup phase, most times we don't do that, right? So this is really what I want to talk. And most of what I've said here, you can see that it has been implemented in the RooStock documentation. You can see the call to actions, which is quick start, and explore the docs. So beginner to F3, deploy smart contract, become a node miner, apply for a grant. Those are different user journeys. And depending on your journey, you can feel free to check out any of those links. So that's an example. All these things, this is an example implementation. Please, if you have questions, kindly go ahead and ask me. Any questions? I have one, though. Yes, please. How much, if I want to come into this line of um technical technical writing what is the entry level what is the because money can be a very good um yeah 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 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 was in charge of preparing their slide decks and like writing about the um the projects they are working on. So I started from open source contributions. So you must not be a developer to contribute to open source. So like I said, a lot of protocols have their 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 chains you interact with, the more your PR rules get merged, the more chains you interact with, the more your PRs get merged, the more experience you can garner. This is not to be replaced with actual work experience, right? Freelance work is different from actual work experience. But open source writing, you can go ahead and share knowledge, whatever, on medium depth or two-hatch nodes. That's also a great way for you to start building your portfolio. Once you have your portfolio together, you can start applying for actual jobs because the 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... So you don't want to give us an amount like 5K, 10K, if you get the job. For a beginner, it depends on the open source. It if you get the job? For a 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 high as $500. It can go as high as $1,000 if it's open source and some of the contests. So we have writing contests on RooStock and Hakanun. So if you go to Google, search Hakanun writing contest, you'll see Rustok. And you can also write about Rustok. And you'll be also, if you are eligible, you will win the prizes. So those are the ways you can get started. Please, a round of applause for Mwanat for this amazing session.