The One Question bounty closes Thursday 10 December.

Join in
We Them Media logo We Them Media Support us

Web3 Documentation Best Practices - Lessons from Rootstock - Wisdom Nwokocha

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

A technical writing mentor talks about Web3 documentation. They argue docs are part of the product, since poor docs lose developers. They cover challenges such as fast-changing technology, jargon and accuracy, and tips: clear short writing, a consistent style guide, screenshots, community feedback, and navigation such as breadcrumbs and search.

Not by We Them Media Channel: Web3Bridge. Published Thursday 3 October 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:05 A: Good afternoon, everyone. Yeah, so today we'll be talking about documentation, specifically Web3 documentation, the best practices. So a few minutes so we can get the slide ready. Okay, yep. All right, so before I go further, so I want to talk about little things that I do. So I have a technical writing mentorship program. If you want to go into technical writing, you want to know how to build API docs and more, you can follow us on Twitter, Technical Writing Mentorship Program, and it's an open source community, so it's free. You're not going to pay any money at all, so it's totally free. All right, next slide, please. So today, I know most of us, we've been trying to go through other Web3 documentation. So I would be giving us tips, telling us little things, those little important stuff that are not on docs that you should take note of. So as a Web3 developer or as a startup person or investor that wants to put money on any Web3 startup, you need to take note of those stuff on documentations because most people don't take it serious because they feel documentation is not the product. But it is. You need to spend more time on that because your developers look out for that stuff. For example, I want to know how to work with a particular protocol. I want to know how they do their mainnet or testnet, how to implement on that stuff. And if the docs is not good, trust me, you've lost a user, you've lost a customer. And if you lose one customer- I know the business guys are here- if you lose one customer, you've lost like 10,000. Because if I go to the docs and I see that the docs is not good, I will definitely tell the other people, hey, don't try this because you're going to face this problem. And they will keep passing that on and on, and at the end of the day, you have very few persons coming to your docs. Sorry, can you show this slide? Okay, next. Yeah, next one. Oh, sorry. Okay, so let's talk about the challenges when it comes to Web3 documentation, which is quite different from Web2 documentation. So one of them is diverse technical audience. So we have the educational gap and we have the stakeholders' needs. So you go to some Web2 documentations and you see normally when you get there, you know, the doc should have several categories, several areas that would accompanying or several areas that would accommodate these different audiences. As a developer, I know I want to know how to install your stuff. I want to know more about your testnet, your, your explorer, and more. And when your docs doesn't have that, it's a problem for me. That's why I see some people go to documentations, and what they will have to do is they will start using forums, Stack Overflow, and more when you have your documentation. So if I don't have that patience, you've lost me already. And, um, some of them don't have those tutorials that will help you learn, which is the educational gap. And having those stakeholders, maybe investors, you have developers, you have cryptographers, and more. So if you have those areas that accommodate them, you would retain those users. So the next one is rapid evolving technology. So you all know how blockchain is moving so fast. You're learning this one, the next morning you're hearing about zk-rollup, the next day you're hearing about bridge, the next day you're hearing about a different new layer 2 that comes up. The next day is meme coin. The next thing is airdrop. Now when all these things are coming up, what would have- what you have in your mind is who will be writing all those things. Now how fast will that person try to cover up all those things? So if I'm writing about meme coin, about my company, the next thing is I want- I'm doing that stuff, they said, okay, that is the bridge is now the popular stuff to move stuff from here to here. So we want to build our bridge. Developers have built it, start writing it. You're writing it, they say, oh, meme coin is now the main stuff. okay, we've built our meme coin, the next thing is airdrop. So that's why you see sometimes, you know, you know, you see sometimes you will see a product or a software or something is way ahead than that documentation. So you're using the product, you're seeing some stuff, but when you go to the documentation, you're not seeing those stuff there. So the next thing is maintaining accuracy and relevance. So which is the constant topic I talked about. So the content update is just too much, and because of that you don't really see, like I said earlier on, the product will be way ahead of the documentation. So that updates is way too much. So copying that will help that a lot. So you have security implementation- implication, sorry. So some documentations, you know, you'll see because of the rapid changes and more, you know, some technical writers or documentation engineers would miss out on the point of making sure they note out those stuff, they make some mistakes when they push in other stuff. So for example, maybe they say you need to run a command before you build or before you deploy to add the security, and the technical writer misses that point. So which means if you deploy, that particular dApp is vulnerable. Anybody can easily, you know, hack that stuff. So they need to pay so much attention to that. So you have visibility and accessibility, which is technical jargon. I know most of us here know about WADME. So when you go, you see Wagmi. I know there are different terms they use on blockchain. So as a first-time user, if you go to a docs and you're seeing Wagmi and there is no description about what that means, you know, you get confused. And one thing I tell my students is if you build a documentation that someone will use Google side by side with that docs, you know, you need to do a lot of work because I'm looking at your docs but I'm using Google. Wagmi, I'll go to Google Wagmi. If I go, I will see the other acronym. I will go to Google and start, and with Google it can give you a word of something else, and you're confusing the person the more. So try to break down those technical jargons. Make sure you add the description next to them. Then you have user presentation. So we are talking more on images and visuals. So images are very, very important, you know, taking screenshots. For example, you want to write a user guide, it's very important for you to take screenshots label it so it's easier for me. If you want to use WhatsApp right now and you're just seeing an article about how to use WhatsApp without no image, you get confused. But when you see an image with some directions, if you click here, this means this, this means that, it will be much easier for you to follow. So the key principles, I will just run that through. So you have clarity, you know, like I said, remove the technical jargons, make it clear. Don't write normally when you talk too much, you won't even know when you're saying rubbish. So just try to be fast, you know, make it concise, don't make it too big. Something that is, let's say, mainnet for production, testnet, you know, for testing, don't start writing long story, just 1-2 sentence, users will understand that. So consistency, that is where we talk about the style guide, which is writing style guide. So we have different writing style guide for different things. So we have writing style guides For technical articles, we have one like the APA style guide. We have many, many something style guide. We have Google writing style guide. We have a Microsoft writing style guide and we have Red Hat. So these 3 writing style guides are mainly for technical articles. And that consistency, what I mean is if you go to an article, maybe you're reading, you see the date, they use date with slash. You go to the next place, you're seeing date with dash. You go to the other section of the page, you're seeing date with bracket or something. That inconsistency is not good. So if you're using slash, use slash all through. If you're bolding your important terms, make sure you bold them. If you're starting a sentence with capital letter, make sure you also do that everywhere. So we have the continuous improvement. So make sure you talk with your developers, you know, talk with the community so they give you updates. You update your documentation, and then this will help you make sure that your documentation is not far away from the product. So your product is on same level as your documentation. So scalability- so there are docs that they'll build a doc normally, you know, most Web3 companies they use GitBook to build their docs. So when they use GitBook and when they've grown a bit big, they will change GitBook and they use maybe Docusaurus or something and maybe style it up and make it look much, much better. So with such documentation you know, you will get scared because I know this is GitBook. You know, when you move to the next docs, you're seeing something different, and that will make you probably- maybe if you're not on their Discord, you want to join their Discord or something, or email them to- I want to be sure that this website that I'm in is the docs, is the actual one, because the one I'm seeing before looks so different from this. So use a docs that you can easily scale, have a look and feel. Even if you decide to move to a different platform, you have that same look and feel. So users, more like an identity. So users know that, okay, this is your product, this is your docs, even if you use a different SSG for that. So visuals, I've talked about that. Community involvement is very important. Always give community the- give them the chance to always review your docs, give you updates, always be open to listen in documentation. So users who said, I was trying to install this and I couldn't do that because of the step, don't joke with that information. Always make sure you work with that. So you have structuring content. So first one is the journey approach. You know, let me use JavaScript for example. So if you want to learn JavaScript, most JavaScript tutorials you see, they have a straightforward journey. Make it simple, start from the simple parts, and when you get to the last part, that is where you see a more advanced one. For example, the first you see may be overview or maybe introduction. The next one you're seeing is maybe installation or setup, maybe how to set up and run that stuff. Next one you're seeing is maybe a comment, and the other one- okay, sorry, probably you always see hello world. Okay, you've, you know what this means, you've set it up or installed it. Now let us do hello world just to welcome you so you know it's simple. Then afterwards you'll see maybe your comments, your variables, and, and as it keeps going down, it's more advanced. So don't start with the advanced stuff and carry the simple ones down because users always start from that side. So make sure you follow that journey in your documentation. So clear navigation between levels to make it very easy. Anywhere I find myself in the docs, I can go to home, I can go back. Majorly I'll use like, is it breadcrumbs or breadcrumbs they call it, that will give you that journey. So, you know, sometimes you go to a docs and maybe you close your laptop or off your laptop, the next day you open it and you would see you won't even know where you are, but you know you're there. Now, how did I get to this place? Yeah, I want to know how I get to this place. It's difficult for you. But if you add that breadcrumbs, I will know the journey. I came from this page to this page to that page, and I can also see get back. There is a search for me to search for something. There is the home button and the back button. You know, these navigation stuff are very important.

11:06 B: Wow. Amazing. That's, that's very, very important. Thank you.

11:13 A: Okay. All right. Yeah. Thank you. So let me push-

11:16 B: If you have questions, we can take one, just one question for-

11:18 A: So you can follow me on Twitter and I'm also on LinkedIn. Thank you.

11:22 B: Please follow Wisdom on Twitter. If you have a question, we can take just one question for Wisdom.

11:27 A: I also have, I also have my book and I have my community shirt to give out to one person. I don't know if I brought it here or something.

11:35 B: Okay, okay, okay. Thank you so much, Wisdom.

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.