Web3 Documentation Best Practices - Lessons from Rootstock - Wisdom Nwokocha

good afternoon everyone yeah so today we'll be talking about um documentation specifically web three documentation the best practices so few minutes so we can get the slide ready okay y all right so um before I go for that 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 dos 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 any money at all so it's totally free all right next slide please so today um I know most of us we've been trying to go through other we three documentation so I would giving us tips telling us little things those little important stuff that are not on docks that you should take note of so as a web pre developer or as a startup person or investor that want to put on money on any web startup you need to take not of those stuff on documentations because most people don't take it serious because the feel documentation not a product but it is you need to spend more time on that cuz your developers look at for that stuff for example I want to know how to work with a particular protocol I want to know how they do their main net or test net how to implement on that stuff and and if the docks 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 cuz if I go to the docks and I see that the dock is not good I would definitely tell the other people hey don't try this if you go 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 docks can I show this light okay next yeah next one okay so let's talk about the challenges when it comes to web 3 documentation which is quite different from Web Two 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 web to documentations and you see normally when you get there you know the dog should have several category several areas that would accompany or several areas that would accommodate this different audience as a developer I know I want to know how to install your stuff I want to know more about your test net your your your Explorer and more and when your dogs 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 stock overflows 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 tutorial 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 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 Z up the next day you're hearing about Bridge the next day you're hearing about different new layer to that comes up the next day is M coin the next thing is air drop 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 would that person try to cover up all those things so if I'm writing about me about my company the next thing is why I'm doing that stuff they said okay that is brid 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 writing it they say oh M coin is now the main stuff okay we've buil our M coin the next thing is air drop so that's why you see sometimes you know you know you see sometimes you will see a product or a software 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 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 and the documentation so that updat is way too much so cing 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 some technical writers or documation Engineers would miss out on the point of making sure they note out those stuff they some mistakes when you push those 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 dap is 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 jagon I know most of us here know about wag me so when you go you see wag me 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 wag me 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 dogs you know you need to do a lot of work cuz I'm looking at your dogs but I'm using Google wag me I go to Google wag me if I go I will see the other name I go to Google and start and we Google it can give you wag me of something else and your confusing the person the more so try to break down those technical Jons make sure you add the description next to them then you have user presentation so we 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 screenshot 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 direction to we click here this means this this means that it 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 say remove the technical drons make it clear don't TR normally when you talk too much you won't even know one 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 main net for production test net you know for testing don't start writing long story just one to sentence users will understand that so consistency that is where we talk about the sty guide which is writing sty guide so we have different writing sty guide for different things so we have writing style guides for technical articles we have one like the upper sty guide we have you see M something St guide we have Google writing sty guide we have Microsoft writing sty guide and we have red heart so these three writing sty guides are mainly for technical articles and that consistency see 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 you slash all through if you're building your important terms make sure you B 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 developer you know talk with the community so they give you update 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 docks that they will build a dog normally you know most web three companies they use G gbook to build their docks so when they use gbook and when they've grown a bit big they will change G book and they use maybe Doos or something and maybe style it up and make look much much better so with such documentation you know you will get scared cuz I know this is gbook 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 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 inan is the docs is the actual one because the one I'm seen before looks so different from this so use a dogs 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 docks even if it is a different SSG for that so visuals I've talked about that Community involvement is very important always give Community the the give them the chance to always review your dogs give you update 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 part and when you get to the last part that is where you see a more advanced one for example the first you seebe 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 is is maybe a comment and the other one okay sorry probably you always see Hello word okay You' you know what this means you've set it up or installed it now let us do hello word just to welcome you so you know it's simple then afterward you 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 I'm car the simple ones down because users always start from that side so make sure you follow that Journey your documentation so clear navigation between levels to make it very easy anywhere I find myself in the docks I can go to home I can go back majorly I use like is it bed crops or brand crops in college that will give you that Journey so you know sometimes you go to a docks and uh 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 is difficult for you but if you add that bed crumbs 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 wow amazing that's that's very very important thank you okay all right yeah thank you so let me push if you have question we can take one just one question for so you can follow me on Twitter and most on LinkedIn thank you follow wisdom on Twitter if you have a question we can take just one question for wisdom I also have a also have my book and I have my community shed to give her to one person I don't know if I brought it or something okay okay okay thank you so much wisdom