The One Question bounty closes Thursday 10 December.

Join in
We Them Media logo We Them Media Support us

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

The picture loads from YouTube. The player loads only when you press Play. Turn on captions in the player if you need them.

Owanate, a senior technical writer at Rootstock Labs, explains how to build good Web3 documentation, drawing on a rebuild of the Rootstock docs. The talk covers knowing the reader, sorting content into concept, developer, node operator and user sections, and tools such as Miro, Excel and Figma. In questions, a newcomer is pointed to open source writing and contests.

Not by We Them Media Channel: Web3Bridge. Published Friday 20 September 2024.

Titles are the owner’s. It plays from their channel.

Transcript

This transcript may contain errors. This video belongs to Web3Bridge. Letters mark each change of speaker.

These are the speakers’ own words. We have not checked their claims.

0:00 A: So I'll be calling Owanate to come and give her next talk. Please, a round of applause for her. I know I crucified that name.

0:10 B: Really, really, really.

0:12 A: Owanate.

0:14 B: 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 documentation, can you please signify before? Okay. Um, how many developers here have built like documentation from scratch, like GitBook? Nice, nice, nice. Okay, so there are some challenges with Web3 documentation, and as we all know, um, 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, I was speaking with somebody, um, here. A developer was complaining about a chain's documentation and, um, how it was very difficult for them to get started and 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 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 1 1 together. So this talk is for doc specialists. 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, on a particular topic on documentation. This topic is very interesting and please pay attention. So I'm Owonate, I'm a senior technical writer at Rootstock Labs, and recently I was I led a project to rebuild the Rootstock documentation from scratch. So when I mean from scratch, from the very scratch, we were using Deque, we moved to Gatsby, and we then moved to Docusaurus. So there was a lot of learning process involved in that, and I would like to walk you through the steps we went through to achieve that. So So we'll be, we'll be under- 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 ideate, 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 poor documentation, um, trust me, you do not know how many, um, how many, 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. Um, and this doc- documentation also helps developers understand and what- 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 includes 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? But like I said, Web3 is still in its nascent stage. So what do you need to do? Most of the- 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 are a developer, if the developer of that chain is the one that sets up the documentation, they are not going to pay attention to user research. They are 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 like design the architecture to suit each particular user. So for example, for Ethereum, for Rootstock, 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 node operator, it needs to get out to the ordinary and general user for that product. So these are 3 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 are beginners, if they are intermediate, if they are experts, what is the ideal journey for the- for those persons? So know your users, right? Understand what they are. What platform do they use? Do they use mobile? Do they use web? Um, who are these developers? Are they Web3 developers? Are they Bitcoin developers? Are the Ethereum developers looking to port 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 if any person coming that is new to your chain knows that they have to start with Hardhat, they have to start with, um, uh, Wagmi, 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 will be good if you have. Previously, um, if you have previously built a developer portal before and you want to like reimagine your documentation, and then for technical writers who are playing on the turf 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, uh, 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, 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 will remember how, um, during when most times people explain blockchain using Web2 databases, sometimes they also explain blockchain using chains. Right? Chains upon chains connected together. So that's a mental model. We know how chains look like, and we can relate that to what 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, um, what's the difference in Web2 and the difference in Web3 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 confuse your audience. So information has to do- 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 intermediates, or for experts. So that's it for information architecture. I'm going to show you, um, how to- what this is, a, a, in the beginning phase, this is a simple information architecture, right? Here, um, you can observe that there are 3, there are 3, um, like 3 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 concepts bucket or whatever you tend 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 understand what and get into that particular bucket. Now node operators, if you want to start up a node as a developer, depends on the chain. Some 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 RPC. So it's not really that efficient if you tell them how to start a node. But if you have- if that's the way you start a node on your chain, please go ahead and put that information in that bucket. So 3, I've done 3 buckets here. 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 RPC to interact with. Okay, so now I've broken this down, um, in this step I've added the developer buckets. Now why did I add the developer bucket? The developer buckets, that means we have concepts, and concepts can talk about what is Ethereum What is Rootstock? What is merge mining? Or what is, um, what is, 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're a developer coming to a documentation that has these 4, um, these 4 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 Starts from there. You see the hardware requirements and how to set up your your system, your environment to start deploying or writing smart contract. 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 have them, how the node operators can set up on your chain, how they can understand the basic information about the node and all that. And then we have the user. So if your chain has 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 an information architecture should look like. So what are the key takeaways from this talk, right? I'm trying to hurry up. Use familiar concepts. In some cases, you see developers, right, um, they create endpoints that are not even- the endpoint is not even- does not concern the particular, um, page or whatever is being developed. So that is one use case. Um, use familiar concepts 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 if you have, um, if you are 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 write smart contract. That way it's helpful for SEO. And when somebody is looking for, um, searching on Google how 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 5 minutes, if possible in 2 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 those are- this is really what I want to talk about. And most of what I've said here, you can see that it has been implemented in the Rootstock documentation. You can see the call to actions, which is quick start, and explore the docs. So beginner to Web3, um, 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 I've said, this is an example implementation. And please, if you have questions, kindly go ahead and ask me.

15:55 A: Any questions? I have one though.

16:00 B: Yes, please.

16:02 A: How much, uh, if I, if I want to join, come into this line of, um,

16:09 B: technical,

16:09 A: technical writing, what is the entry level? What is the- because money can be a very good, um,

16:18 B: yeah,

16:18 A: motivation, you know.

16:19 B: Yeah, motivation.

16:19 A: And most people are just looking like they are here for the passion. No, yeah, yeah. So what, what are we looking at when it comes to, to that?

16:28 B: 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. Yeah. 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, chains you interact with, the more, um, your, 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. Yeah. But open source writing, um, you can go ahead and share knowledge, whatever, on Medium, dev.to, Hashnode. 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 want to see your portfolio, and there's no way you can get a portfolio if you don't start writing. So that's the-

17:35 A: like, so, so you don't want to give us an amount like, like $5K, $10K if you get it?

17:41 B: 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 far as high as $500. go as high as $1K if it's open source and some of the contests. So we have writing contests on Rootstock on HackerNoon. So if you go to Google, search HackerNoon writing contest, you'll see Rootstock, and you can also write about Rootstock, and you'll be also- if you are eligible, you win the prizes. So that's- those are the ways you can get started.

18:12 A: Please, a round of applause for Wanat for this amazing session.

More from this hub

Something wrong, or a video you want off this page? Write to wethem.xyz@gmail.com and it is fixed or taken down within 48 hours.